@devlab.group/agent-commerce 2.4.1 → 2.5.0

package/dist/index.js

@@ -1,18 +1,18 @@
-import { openSqliteDatabase, AP2_SPEC_VERSION, AP2_MODES, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_JWK_MEMBERS, AP2_KEY_TYPE, AP2_SIGNING_ALGORITHM, AP2_JWK_CURVE, AP2_JWK_COORDINATE_BYTES, AP2_MAX_CLOCK_SKEW_SECONDS } from './chunk-WZW5ORZH.js';
+import { openSqliteDatabase, AP2_SPEC_VERSION, AP2_MODES, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_JWK_MEMBERS, AP2_KEY_TYPE, AP2_SIGNING_ALGORITHM, AP2_JWK_CURVE, AP2_JWK_COORDINATE_BYTES, AP2_MAX_CLOCK_SKEW_SECONDS } from './chunk-VUCMBGUR.js';
 import { readCappedBody, createBearerCheck, MCP_TOOL_NAME_PATTERN, settlementResponse, joinUrl, settlementResponseFromDetails, settlementFailure, x402ErrorCode, x402RefusalStatus } from './chunk-ES3V6ECS.js';
 import { MPP_DEFAULT_NETWORK, isMppNetwork, MPP_NETWORKS, MPP_DEFAULT_PAYMENT_FLOW, MPP_MIN_CHALLENGE_SECRET_LENGTH, MPP_PROFILE } from './chunk-6Z2H53CG.js';
 import { contentDigest, CONTENT_DIGEST_METADATA_KEY, mppProblem, mppProblemDetail } from './chunk-5ZYXBCDX.js';
-import { X402_PAYMENT_FLOWS, validateCustomNetworks, findX402Network, X402_DEFAULT_PAYMENT_FLOW, resolveX402Deployment, SETTLE_AFTER_BACKEND_METADATA_KEY, resolveDeploymentMode, requireX402Network, resolveX402Option, isEvmAddress, isEvmZeroAddress, x402OfferName, REUSE_REJECTED_AUTHORIZATION_METADATA_KEY } from './chunk-QPV3EGJO.js';
-import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_METHOD_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, isCommerceError, describeError, isHttpProtocolAdapter, toLogInfo, extractReservedInputFields, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, toErrorEnvelope, DELIVERY_SUMMARY_META_KEY, toDeliverySummary, PAYMENT_INPUT_FIELD, AUTHORIZATION_INPUT_FIELD, parseAuthorizationSubmission } from './chunk-DTKU3Z2M.js';
-export { AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, MAX_AUTHORIZATION_HEADER_BYTES, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_METHOD_NAMES, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, extractReservedInputFields, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, parseAuthorizationHeader, parseAuthorizationSubmission, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-DTKU3Z2M.js';
+import { X402_PAYMENT_FLOWS, validateCustomNetworks, findX402Network, X402_DEFAULT_PAYMENT_FLOW, resolveX402Deployment, resolveDeploymentMode, requireX402Network, resolveX402Option, isEvmAddress, isEvmZeroAddress, SETTLE_AFTER_BACKEND_METADATA_KEY, x402OfferName, REUSE_REJECTED_AUTHORIZATION_METADATA_KEY, canonicalJson } from './chunk-4K7FIBJM.js';
+import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_METHOD_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, CommerceError, systemClock, NOOP_LOGGER, transactionState, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, isCommerceError, describeError, isHttpProtocolAdapter, toLogInfo, extractReservedInputFields, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, toErrorEnvelope, DELIVERY_SUMMARY_META_KEY, toDeliverySummary, PAYMENT_INPUT_FIELD, AUTHORIZATION_INPUT_FIELD, parseAuthorizationSubmission, RECONCILIATION_METADATA_KEY, TRANSACTION_STATES, redactedErrorText } from './chunk-3OTCFFFT.js';
+export { AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, MAX_AUTHORIZATION_HEADER_BYTES, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_METHOD_NAMES, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RECONCILIATION_METADATA_KEY, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, TRANSACTION_STATES, extractReservedInputFields, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, parseAuthorizationHeader, parseAuthorizationSubmission, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope, transactionState } from './chunk-3OTCFFFT.js';
 import { isRecord } from './chunk-2CJNA7MS.js';
 import { promises, accessSync, constants } from 'fs';
 import * as path from 'path';
 import { parse, YAMLError } from 'yaml';
 import { z } from 'zod';
+import { randomUUID, createHash } from 'crypto';
 import { isDeepStrictEqual } from 'util';
 import Fastify from 'fastify';
-import { randomUUID, createHash } from 'crypto';
 import { createRequire } from 'module';
 import pino from 'pino';
 import { Transform } from 'stream';
@@ -1169,7 +1169,7 @@ var TRAVERSAL_PATH_VALUES = /* @__PURE__ */ new Set(["", ".", ".."]);
 function applyPathTemplate(template, input, context) {
   const remaining = { ...input };
   let missing;
-  let invalid2;
+  let invalid3;
   const url = template.replace(PATH_PARAM_PATTERN, (_match, key) => {
     if (!Object.hasOwn(remaining, key)) {
       missing = key;
@@ -1179,7 +1179,7 @@ function applyPathTemplate(template, input, context) {
     delete remaining[key];
     const raw = stringifyPrimitive(value);
     if (TRAVERSAL_PATH_VALUES.has(raw)) {
-      invalid2 = key;
+      invalid3 = key;
       return "";
     }
     return encodeURIComponent(raw);
@@ -1190,10 +1190,10 @@ function applyPathTemplate(template, input, context) {
       details: { field: missing }
     });
   }
-  if (invalid2 !== void 0) {
-    throw new CommerceError("INPUT_INVALID", `Path parameter "${invalid2}" is not a valid value`, {
+  if (invalid3 !== void 0) {
+    throw new CommerceError("INPUT_INVALID", `Path parameter "${invalid3}" is not a valid value`, {
       ...context,
-      details: { field: invalid2 }
+      details: { field: invalid3 }
     });
   }
   return { url, remaining };
@@ -1446,6 +1446,56 @@ function safeStringify(value) {
 function isAbortError(error) {
   return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
 }
+function createFlow(request, transactionId) {
+  return { request, transactionId, persistenceFailures: [], journaled: false };
+}
+function failuresOf(flow) {
+  return flow.persistenceFailures.length > 0 ? { persistenceFailures: [...flow.persistenceFailures] } : {};
+}
+function sha256(text) {
+  return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+function inputDigest(input) {
+  const json = canonicalJson(input);
+  return json !== void 0 ? sha256(json) : void 0;
+}
+function configDigest(resource, requirement) {
+  const terms = {
+    resourceId: resource.id,
+    pricing: resource.pricing,
+    paymentMethods: resource.paymentMethods,
+    authorization: resource.authorization?.required ?? [],
+    requirement: {
+      provider: requirement.provider,
+      amount: requirement.amount,
+      currency: requirement.currency,
+      destination: requirement.destination ?? null,
+      network: requirement.network ?? null,
+      asset: requirement.asset ?? null,
+      settleAfterBackend: requirement.metadata?.[SETTLE_AFTER_BACKEND_METADATA_KEY] === true
+    }
+  };
+  return sha256(canonicalJson(terms) ?? JSON.stringify(terms));
+}
+function newTransaction(flow, resource, requirement, verification, validInput, authorization) {
+  const raw = verification.metadata?.[RECONCILIATION_METADATA_KEY];
+  const locator = isRecord(raw) ? raw : void 0;
+  const expiresAt = typeof locator?.["expiresAt"] === "string" ? locator["expiresAt"] : void 0;
+  const network = verification.network ?? requirement.network;
+  const asset = verification.asset ?? requirement.asset;
+  const digest = inputDigest(validInput);
+  return {
+    id: flow.transactionId,
+    protocol: flow.request.protocol,
+    ...network !== void 0 ? { network } : {},
+    ...asset !== void 0 ? { asset } : {},
+    ...locator !== void 0 ? { locator } : {},
+    ...expiresAt !== void 0 ? { expiresAt } : {},
+    ...authorization !== void 0 ? { authorization } : {},
+    ...digest !== void 0 ? { inputDigest: digest } : {},
+    configDigest: configDigest(resource, requirement)
+  };
+}
 var SUPPORTED_TYPES = /* @__PURE__ */ new Set([
   "object",
   "string",
@@ -1588,16 +1638,15 @@ function resolveAuthorizationProviders(providers, resource, requestId) {
 }
 function createAuthorizeAndReserve(ctx) {
   const { options, safeEmit, buildEvent } = ctx;
-  async function authorizeAndReserve(request, resource, providers, requirement, input) {
+  async function authorizeAndReserve(flow, request, resource, providers, requirement, input) {
     if (providers.length === 0) return void 0;
     const submission = request.authorization;
     const provider = providers.find((candidate) => candidate.name === submission?.method);
     const unmet = providers.filter((candidate) => candidate !== provider).map((c) => c.name);
     if (submission === void 0 || provider === void 0 || unmet.length > 0) {
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "authorization.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           status: "error",
@@ -1634,9 +1683,8 @@ function createAuthorizeAndReserve(ctx) {
         }
       );
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "authorization.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           status: "error",
@@ -1646,9 +1694,8 @@ function createAuthorizeAndReserve(ctx) {
       throw mapped;
     }
     await safeEmit(
-      buildEvent({
+      buildEvent(flow, {
         type: "authorization.verified",
-        requestId: request.requestId,
         resourceId: resource.id,
         adapter: request.protocol,
         status: "ok",
@@ -1662,14 +1709,17 @@ function createAuthorizeAndReserve(ctx) {
         reference: verification.reference,
         ...verification.metadata !== void 0 ? { metadata: verification.metadata } : {}
       },
+      reservationId: verification.reservationId,
       async finalize(action) {
         try {
           await provider[action](verification.reservationId, context);
+          return true;
         } catch (error) {
           options.logger.error(
             { err: describeError(error), requestId: request.requestId, action },
             "Authorization finalization failed; the reservation stays reserved"
           );
+          return false;
         }
       }
     };
@@ -1710,7 +1760,7 @@ function replayError(error, requirement) {
 // src/core/execution/pipeline/admission.ts
 function createPaymentAdmission(ctx, authorizeAndReserve) {
   const { options, safeEmit, buildEvent } = ctx;
-  return async function admitPayment(request, resource, pricing, validInput) {
+  return async function admitPayment(flow, request, resource, pricing, validInput) {
     const provider = pickProvider(options.paymentProviders, resource.paymentMethods);
     if (!provider) {
       throw new CommerceError(
@@ -1749,9 +1799,8 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
     }
     if (!request.payment) {
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "payment.required",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           paymentProvider: provider.name
@@ -1760,6 +1809,7 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
       return {
         kind: "payment-required",
         requestId: request.requestId,
+        transactionId: flow.transactionId,
         resourceId: resource.id,
         requirement,
         ...authProviders.length > 0 ? { authorization: authProviders.map((p) => p.requirement) } : {}
@@ -1790,9 +1840,8 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
         ...retryChallenge(requirement)
       });
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "payment.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           paymentProvider: provider.name,
@@ -1804,9 +1853,8 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
     }
     if (verification.status !== "verified") {
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "payment.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           paymentProvider: provider.name,
@@ -1826,9 +1874,8 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
     }
     if (!verification.replayKey) {
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "payment.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           paymentProvider: provider.name,
@@ -1843,6 +1890,7 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
     }
     const replayKey = verification.replayKey;
     const hold = await authorizeAndReserve(
+      flow,
       request,
       resource,
       authProviders,
@@ -1850,7 +1898,7 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
       validInput
     );
     try {
-      await options.store.reservePaymentAttempt({
+      const attempt = await options.store.reservePaymentAttempt({
         requestId: request.requestId,
         resourceId: resource.id,
         provider: provider.name,
@@ -1859,8 +1907,17 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
         currency: verification.currency,
         ...verification.payer !== void 0 ? { payer: verification.payer } : {},
         ...verification.payee !== void 0 ? { payee: verification.payee } : {},
-        ...requirement.metadata?.[REUSE_REJECTED_AUTHORIZATION_METADATA_KEY] === true ? { reclaimRejected: true } : {}
+        ...requirement.metadata?.[REUSE_REJECTED_AUTHORIZATION_METADATA_KEY] === true ? { reclaimRejected: true } : {},
+        transaction: newTransaction(
+          flow,
+          resource,
+          requirement,
+          verification,
+          validInput,
+          hold !== void 0 ? { ...hold.record, reservationId: hold.reservationId } : void 0
+        )
       });
+      flow.journaled = attempt.transactionId === flow.transactionId && options.store.recordTransactionStep !== void 0;
     } catch (error) {
       const mapped = toCommerceError(
         error,
@@ -1869,9 +1926,8 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
       );
       await hold?.finalize("release");
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "payment.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           paymentProvider: provider.name,
@@ -1882,9 +1938,8 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
       throw replayError(mapped, requirement);
     }
     await safeEmit(
-      buildEvent({
+      buildEvent(flow, {
         type: "payment.verified",
-        requestId: request.requestId,
         resourceId: resource.id,
         adapter: request.protocol,
         paymentProvider: provider.name,
@@ -1894,6 +1949,7 @@ function createPaymentAdmission(ctx, authorizeAndReserve) {
     return {
       kind: "admitted",
       settleArgs: {
+        flow,
         request,
         resource,
         provider,
@@ -1915,6 +1971,11 @@ function pickProvider(providers, methods) {
 }
 
 // src/core/execution/pipeline/context.ts
+var HOLD_STATES = {
+  consume: "consumed",
+  release: "released",
+  markUncertain: "uncertain"
+};
 function createPipelineContext(options) {
   async function safeEmit(event) {
     try {
@@ -1926,27 +1987,73 @@ function createPipelineContext(options) {
       );
     }
   }
-  async function safePersist(op, label, requestId) {
+  async function safePersist(flow, op, label, failure) {
     try {
       await op();
+      return true;
     } catch (error) {
       options.logger.error(
-        { err: describeError(error), requestId },
+        {
+          err: describeError(error),
+          requestId: flow.request.requestId,
+          transactionId: flow.transactionId
+        },
         `Persistence failed: ${label}`
       );
+      if (failure !== void 0 && !flow.persistenceFailures.includes(failure)) {
+        flow.persistenceFailures.push(failure);
+      }
+      return false;
     }
   }
-  function buildEvent(partial) {
-    return { id: options.ids.next("evt"), at: options.clock.nowIso(), ...partial };
+  async function recordStep(flow, step) {
+    const record = options.store.recordTransactionStep;
+    if (!flow.journaled || record === void 0) return;
+    const full = {
+      ...step,
+      transactionId: flow.transactionId,
+      at: options.clock.nowIso()
+    };
+    await safePersist(
+      flow,
+      () => record.call(options.store, full),
+      `recordTransactionStep(${step.kind})`,
+      "journal"
+    );
+  }
+  async function finalizeHold(flow, hold, action) {
+    if (hold !== void 0 && await hold.finalize(action)) {
+      await recordStep(flow, { kind: "hold", hold: HOLD_STATES[action] });
+    }
   }
-  return { options, safeEmit, safePersist, buildEvent };
+  function buildEvent(flow, partial) {
+    return {
+      id: options.ids.next("evt"),
+      at: options.clock.nowIso(),
+      requestId: flow.request.requestId,
+      transactionId: flow.transactionId,
+      ...partial
+    };
+  }
+  return { options, safeEmit, safePersist, recordStep, finalizeHold, buildEvent };
 }
 
 // src/core/execution/pipeline/settlement.ts
 function createSettlement(ctx) {
-  const { options, safeEmit, safePersist, buildEvent } = ctx;
+  const { options, safeEmit, safePersist, recordStep, finalizeHold, buildEvent } = ctx;
   async function settle(args) {
-    const { request, resource, provider, requirement, payment, verification, replayKey, hold } = args;
+    const {
+      flow,
+      request,
+      resource,
+      provider,
+      requirement,
+      payment,
+      verification,
+      replayKey,
+      hold
+    } = args;
+    await recordStep(flow, { kind: "settling" });
     let settlement;
     try {
       settlement = await provider.settle({
@@ -1959,25 +2066,29 @@ function createSettlement(ctx) {
     } catch (error) {
       const notSubmitted = notSubmittedReason(error);
       if (notSubmitted !== void 0) {
-        await hold?.finalize("release");
+        await finalizeHold(flow, hold, "release");
         await safePersist(
+          flow,
           () => options.store.updatePaymentAttempt({
             replayKey,
             status: "rejected",
             rejectionReason: notSubmitted
           }),
           "updatePaymentAttempt(not-submitted)",
-          request.requestId
+          "payment-attempt"
         );
         await safeEmit(
-          buildEvent({
+          buildEvent(flow, {
             type: "payment.rejected",
-            requestId: request.requestId,
             resourceId: resource.id,
             adapter: request.protocol,
             paymentProvider: provider.name,
             status: "error",
-            data: { reason: "settlement-not-submitted", providerReason: notSubmitted }
+            data: {
+              reason: "settlement-not-submitted",
+              providerReason: notSubmitted,
+              ...failuresOf(flow)
+            }
           })
         );
         throw new CommerceError(
@@ -1987,8 +2098,9 @@ function createSettlement(ctx) {
         );
       }
       const txHash = settlementTxHash(error);
-      await hold?.finalize("markUncertain");
+      await finalizeHold(flow, hold, "markUncertain");
       await safePersist(
+        flow,
         () => options.store.updatePaymentAttempt({
           replayKey,
           status: "settlement-uncertain",
@@ -1996,19 +2108,19 @@ function createSettlement(ctx) {
           ...error instanceof Error ? { rejectionReason: error.message } : {}
         }),
         "updatePaymentAttempt(settlement-uncertain)",
-        request.requestId
+        "payment-attempt"
       );
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "payment.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           paymentProvider: provider.name,
           status: "error",
           data: {
             reason: "settlement-uncertain",
-            ...txHash !== void 0 ? { transactionHash: txHash } : {}
+            ...txHash !== void 0 ? { transactionHash: txHash } : {},
+            ...failuresOf(flow)
           }
         })
       );
@@ -2024,8 +2136,9 @@ function createSettlement(ctx) {
       });
     }
     if (settlement.status !== "settled") {
-      await hold?.finalize("release");
+      await finalizeHold(flow, hold, "release");
       await safePersist(
+        flow,
         () => options.store.updatePaymentAttempt({
           replayKey,
           status: "rejected",
@@ -2033,17 +2146,19 @@ function createSettlement(ctx) {
           ...settlement.externalReference !== void 0 ? { externalReference: settlement.externalReference } : {}
         }),
         "updatePaymentAttempt(rejected)",
-        request.requestId
+        "payment-attempt"
       );
       await safeEmit(
-        buildEvent({
+        buildEvent(flow, {
           type: "payment.rejected",
-          requestId: request.requestId,
           resourceId: resource.id,
           adapter: request.protocol,
           paymentProvider: provider.name,
           status: "error",
-          data: settlement.rejectionReason ? { reason: settlement.rejectionReason } : {}
+          data: {
+            ...settlement.rejectionReason ? { reason: settlement.rejectionReason } : {},
+            ...failuresOf(flow)
+          }
         })
       );
       const rejectionDetails = retryChallenge(requirement, settlement.rejectionReason).details;
@@ -2061,20 +2176,20 @@ function createSettlement(ctx) {
         }
       );
     }
-    await hold?.finalize("consume");
+    await finalizeHold(flow, hold, "consume");
     await safePersist(
+      flow,
       () => options.store.updatePaymentAttempt({
         replayKey,
         status: "settled",
         ...settlement.externalReference !== void 0 ? { externalReference: settlement.externalReference } : {}
       }),
       "updatePaymentAttempt(settled)",
-      request.requestId
+      "payment-attempt"
     );
     await safeEmit(
-      buildEvent({
+      buildEvent(flow, {
         type: "payment.settled",
-        requestId: request.requestId,
         resourceId: resource.id,
         adapter: request.protocol,
         paymentProvider: provider.name,
@@ -2084,26 +2199,26 @@ function createSettlement(ctx) {
     return settlement;
   }
   async function abandonSettlement(args, backendErrorCode) {
-    const { request, resource, provider, replayKey, hold } = args;
-    await hold?.finalize("release");
+    const { flow, request, resource, provider, replayKey, hold } = args;
+    await finalizeHold(flow, hold, "release");
     await safePersist(
+      flow,
       () => options.store.updatePaymentAttempt({
         replayKey,
         status: "rejected",
         rejectionReason: "backend_failed"
       }),
       "updatePaymentAttempt(backend-failed)",
-      request.requestId
+      "payment-attempt"
     );
     await safeEmit(
-      buildEvent({
+      buildEvent(flow, {
         type: "payment.rejected",
-        requestId: request.requestId,
         resourceId: resource.id,
         adapter: request.protocol,
         paymentProvider: provider.name,
         status: "error",
-        data: { reason: "backend-failed", backendErrorCode }
+        data: { reason: "backend-failed", backendErrorCode, ...failuresOf(flow) }
       })
     );
   }
@@ -2140,7 +2255,7 @@ function createExecutionPipeline(options) {
     return compiled;
   }
   const ctx = createPipelineContext(options);
-  const { safeEmit, safePersist, buildEvent } = ctx;
+  const { safeEmit, safePersist, recordStep, buildEvent } = ctx;
   const { settle, abandonSettlement } = createSettlement(ctx);
   const admitPayment = createPaymentAdmission(ctx, createAuthorizeAndReserve(ctx));
   async function execute(request) {
@@ -2156,10 +2271,10 @@ function createExecutionPipeline(options) {
         }
       );
     }
+    const flow = createFlow(request, options.ids.next("txn"));
     await safeEmit(
-      buildEvent({
+      buildEvent(flow, {
         type: "resource.requested",
-        requestId: request.requestId,
         resourceId: resource.id,
         adapter: request.protocol
       })
@@ -2204,20 +2319,34 @@ function createExecutionPipeline(options) {
         }
       );
     }
-    let paymentResult;
-    let authorization;
-    let deferredSettlement;
+    let settleArgs;
     if (resource.pricing.type === "fixed") {
-      const admission = await admitPayment(request, resource, resource.pricing, validInput);
+      const admission = await admitPayment(flow, request, resource, resource.pricing, validInput);
       if (admission.kind === "payment-required") return admission;
-      const { settleArgs } = admission;
-      authorization = settleArgs.hold?.record;
+      settleArgs = admission.settleArgs;
+    }
+    try {
+      return await settleAndDeliver(flow, resource, validInput, settleArgs, pipelineStart);
+    } finally {
+      await recordStep(flow, { kind: "completed", ...failuresOf(flow) });
+    }
+  }
+  async function settleAndDeliver(flow, resource, validInput, settleArgs, pipelineStart) {
+    const { request } = flow;
+    const authorization = settleArgs?.hold?.record;
+    let paymentResult;
+    let deferredSettlement;
+    if (settleArgs !== void 0) {
       if (settleArgs.requirement.metadata?.[SETTLE_AFTER_BACKEND_METADATA_KEY] === true) {
         deferredSettlement = settleArgs;
       } else {
         paymentResult = await settle(settleArgs);
       }
     }
+    await recordStep(flow, {
+      kind: "backend-dispatched",
+      deadlineAt: backendDeadline(options.clock.now(), resource)
+    });
     const backendStart = options.clock.monotonicMs();
     let backendResponse;
     try {
@@ -2230,18 +2359,23 @@ function createExecutionPipeline(options) {
       });
     } catch (error) {
       const commerceError = toCommerceError(error, "BACKEND_ERROR", "Backend call failed");
-      await safeEmit(
-        buildEvent({
+      await recordStep(flow, {
+        kind: "backend-result",
+        status: backendErrorStatus(commerceError),
+        errorCode: commerceError.code
+      });
+      const backendFailed = (data = {}) => safeEmit(
+        buildEvent(flow, {
           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 }
+          data: { code: commerceError.code, ...data }
         })
       );
       if (deferredSettlement !== void 0) {
+        await backendFailed();
         await abandonSettlement(deferredSettlement, commerceError.code);
         throw commerceError;
       }
@@ -2255,13 +2389,11 @@ function createExecutionPipeline(options) {
           protocol: request.protocol,
           payment: paymentResult,
           ...authorization !== void 0 ? { authorization } : {},
-          metadata: { delivered: false, backendErrorCode: commerceError.code }
+          metadata: { delivered: false, backendErrorCode: commerceError.code },
+          transactionId: flow.transactionId
         };
-        await safePersist(
-          () => options.store.saveReceipt(failedReceipt),
-          "saveReceipt(backend-failed-after-settlement)",
-          request.requestId
-        );
+        await saveReceipt(flow, failedReceipt, "saveReceipt(backend-failed-after-settlement)");
+        await backendFailed(failuresOf(flow));
         throw new CommerceError(
           "BACKEND_ERROR",
           "Payment settled but the backend call failed; the payment was not refunded automatically",
@@ -2285,12 +2417,13 @@ function createExecutionPipeline(options) {
           }
         );
       }
+      await backendFailed();
       throw commerceError;
     }
+    await recordStep(flow, { kind: "backend-result", status: backendResponse.status });
     await safeEmit(
-      buildEvent({
+      buildEvent(flow, {
         type: "backend.called",
-        requestId: request.requestId,
         resourceId: resource.id,
         adapter: request.protocol,
         status: "ok",
@@ -2310,34 +2443,48 @@ function createExecutionPipeline(options) {
       durationMs: backendResponse.durationMs,
       protocol: request.protocol,
       ...paymentResult !== void 0 ? { payment: paymentResult } : {},
-      ...authorization !== void 0 ? { authorization } : {}
+      ...authorization !== void 0 ? { authorization } : {},
+      transactionId: flow.transactionId
     };
-    await safePersist(() => options.store.saveReceipt(receipt), "saveReceipt", request.requestId);
+    await saveReceipt(flow, receipt, "saveReceipt");
     const totalDurationMs = Math.round(options.clock.monotonicMs() - pipelineStart);
+    const failures = failuresOf(flow);
     await safeEmit(
-      buildEvent({
+      buildEvent(flow, {
         type: "resource.delivered",
-        requestId: request.requestId,
         resourceId: resource.id,
         adapter: request.protocol,
         status: "ok",
-        durationMs: totalDurationMs
+        durationMs: totalDurationMs,
+        ...failures.persistenceFailures !== void 0 ? { data: failures } : {}
       })
     );
     return {
       kind: "delivered",
       requestId: request.requestId,
+      transactionId: flow.transactionId,
       resourceId: resource.id,
       backendStatus: backendResponse.status,
       body: backendResponse.body,
       headers: backendResponse.headers,
       ...paymentResult !== void 0 ? { payment: paymentResult } : {},
       receipt,
-      durationMs: totalDurationMs
+      durationMs: totalDurationMs,
+      ...failures
     };
   }
+  async function saveReceipt(flow, receipt, label) {
+    if (await safePersist(flow, () => options.store.saveReceipt(receipt), label, "receipt")) {
+      await recordStep(flow, { kind: "receipt", receiptId: receipt.id });
+    }
+  }
   return { execute };
 }
+var BACKEND_DEADLINE_MARGIN_MS = 5e3;
+function backendDeadline(dispatchedAt, resource) {
+  const timeoutMs = resource.handler.timeoutMs ?? DEFAULT_BACKEND_TIMEOUT_MS;
+  return new Date(dispatchedAt.getTime() + timeoutMs + BACKEND_DEADLINE_MARGIN_MS).toISOString();
+}
 function backendErrorStatus(error) {
   const status = error.details?.["status"];
   return typeof status === "number" ? status : 0;
@@ -3468,6 +3615,168 @@ function wrapPino(instance) {
   return logger;
 }
 
+// src/core/execution/reconcile.ts
+var DEFAULT_RECONCILE_MIN_AGE_MS = 15 * 60 * 1e3;
+function journalOf(store) {
+  const {
+    listTransactions,
+    getTransaction,
+    getPaymentAttempt,
+    resolvePaymentAttempt,
+    recordTransactionStep
+  } = store;
+  if (!listTransactions || !getTransaction || !getPaymentAttempt || !resolvePaymentAttempt || !recordTransactionStep) {
+    throw new CommerceError("STORAGE_ERROR", "The receipt store has no transaction journal");
+  }
+  return {
+    listTransactions: listTransactions.bind(store),
+    getTransaction: getTransaction.bind(store),
+    getPaymentAttempt: getPaymentAttempt.bind(store),
+    resolvePaymentAttempt: resolvePaymentAttempt.bind(store),
+    recordTransactionStep: recordTransactionStep.bind(store)
+  };
+}
+var REFUSAL_MESSAGES = {
+  already_resolved: "The payment attempt already has a resolution",
+  not_resolvable: "Only reserved, settlement-uncertain and failed payment attempts can be resolved",
+  too_recent: "The payment attempt is reserved and may still be in flight; retry once it is 15 minutes old",
+  not_expired: "The recorded authorization expiry is still in the future",
+  expiry_unknown: "No expiry is recorded for this authorization; confirm that it has expired"
+};
+var MAX_ACTOR_LENGTH = 256;
+var MAX_REASON_LENGTH = 1024;
+var MAX_REFERENCE_LENGTH = 256;
+var RESOLVABLE = [
+  "reserved",
+  "settlement-uncertain",
+  "failed"
+];
+async function resolveManually(options) {
+  const { clock, logger, attemptId, status, externalReference } = options;
+  if (status !== "settled" && status !== "rejected") {
+    throw invalid("status", 'status must be "settled" or "rejected"');
+  }
+  const actor = requiredText(options.actor, "actor", MAX_ACTOR_LENGTH);
+  const reason = requiredText(options.reason, "reason", MAX_REASON_LENGTH);
+  if (externalReference !== void 0) {
+    requiredText(externalReference, "externalReference", MAX_REFERENCE_LENGTH);
+  }
+  const journal = journalOf(options.store);
+  const attempt = await journal.getPaymentAttempt(attemptId);
+  if (attempt === void 0) {
+    throw new CommerceError("RESOURCE_NOT_FOUND", `Payment attempt "${attemptId}" was not found`);
+  }
+  const refuse = (refusal, current2 = attempt) => ({
+    resolved: false,
+    refusal,
+    message: REFUSAL_MESSAGES[refusal],
+    attempt: current2
+  });
+  if (attempt.resolution !== void 0) return refuse("already_resolved");
+  if (!RESOLVABLE.includes(attempt.status)) return refuse("not_resolvable");
+  if (attempt.status === "reserved" && !(clock.now().getTime() - Date.parse(attempt.createdAt) >= DEFAULT_RECONCILE_MIN_AGE_MS)) {
+    return refuse("too_recent");
+  }
+  const transaction = attempt.transactionId !== void 0 ? await journal.getTransaction(attempt.transactionId) : void 0;
+  if (status === "rejected") {
+    const expiresAt = Date.parse(transaction?.payment.expiresAt ?? "");
+    if (expiresAt > clock.now().getTime()) return refuse("not_expired");
+    if (Number.isNaN(expiresAt) && options.confirmExpired !== true) {
+      return refuse("expiry_unknown");
+    }
+  }
+  const written = await journal.resolvePaymentAttempt({
+    attemptId,
+    expectedStatus: attempt.status,
+    status,
+    ...status === "rejected" ? { rejectionReason: "not_settled" } : {},
+    resolution: {
+      method: "manual",
+      actor,
+      reason,
+      at: clock.nowIso(),
+      ...externalReference !== void 0 ? { externalReference } : {}
+    }
+  });
+  const current = await journal.getPaymentAttempt(attemptId) ?? attempt;
+  if (!written) {
+    return refuse(
+      current.resolution !== void 0 ? "already_resolved" : "not_resolvable",
+      current
+    );
+  }
+  const resolved = transaction !== void 0 ? await journal.getTransaction(transaction.id) : void 0;
+  const target = resolved !== void 0 ? holdTarget(resolved) : void 0;
+  const hold = resolved !== void 0 && target !== void 0 ? await alignHold(resolved, target, {
+    journal,
+    authorizationProviders: options.authorizationProviders,
+    clock,
+    logger
+  }) : void 0;
+  return { resolved: true, attempt: current, ...hold !== void 0 ? { hold } : {} };
+}
+function requiredText(value, field, max) {
+  if (value.trim() === "" || value.length > max) {
+    throw invalid(field, `${field} must be non-empty and at most ${max} characters`);
+  }
+  return value;
+}
+function invalid(field, message) {
+  return new CommerceError("INPUT_INVALID", message, { details: { field } });
+}
+function holdTarget(transaction) {
+  const hold = transaction.authorization?.hold;
+  if (hold !== "reserved" && hold !== "uncertain") return void 0;
+  if (transaction.payment.status === "settled") return "consumed";
+  if (transaction.payment.status === "rejected") return "released";
+  return void 0;
+}
+function holdEntry(transaction, hold, written, reason) {
+  return {
+    transactionId: transaction.id,
+    attemptId: transaction.payment.attemptId,
+    method: transaction.authorization?.method ?? "",
+    hold,
+    written,
+    ...reason !== void 0 ? { reason } : {}
+  };
+}
+async function alignHold(transaction, target, deps) {
+  const authorization = transaction.authorization;
+  const provider = deps.authorizationProviders.find(
+    (candidate) => candidate.name === authorization?.method
+  );
+  if (authorization === void 0 || provider === void 0) {
+    return holdEntry(transaction, target, false, "provider_not_enabled");
+  }
+  const context = { requestId: transaction.requestId, resourceId: transaction.resourceId };
+  try {
+    if (target === "consumed") await provider.consume(authorization.reservationId, context);
+    else await provider.release(authorization.reservationId, context);
+  } catch (err) {
+    deps.logger?.warn(
+      { transactionId: transaction.id, method: provider.name, err: redactedErrorText(err) },
+      "reconcile: authorization provider threw"
+    );
+    return holdEntry(transaction, target, false, "provider_error");
+  }
+  try {
+    await deps.journal.recordTransactionStep({
+      transactionId: transaction.id,
+      at: deps.clock.nowIso(),
+      kind: "hold",
+      hold: target
+    });
+  } catch (err) {
+    deps.logger?.warn(
+      { transactionId: transaction.id, err: redactedErrorText(err) },
+      "reconcile: could not record the hold update"
+    );
+    return holdEntry(transaction, target, false, "journal_error");
+  }
+  return holdEntry(transaction, target, true);
+}
+
 // src/gateway/public-resource.ts
 function toPublicResource(resource) {
   return {
@@ -3721,6 +4030,15 @@ function buildWellKnownDocument(options) {
 
 // src/gateway/routes.ts
 var X402_V1_PAYMENT_HEADER = "x-payment";
+var RESOLVE_BODY_LIMIT_BYTES = 4096;
+var RESOLVE_FIELDS = [
+  "status",
+  "actor",
+  "reason",
+  "externalReference",
+  "confirmExpired"
+];
+var TRANSACTION_EVENT_LIMIT = 50;
 function registerRoutes(options) {
   const { server } = options;
   const readinessProbe = createReadinessProbe({
@@ -3788,6 +4106,113 @@ function registerRoutes(options) {
       )
     )
   );
+  const { store, clock } = options;
+  const journal = () => journalOf(store);
+  const withAge = (transaction) => ({
+    ...transaction,
+    ageSeconds: Math.max(
+      0,
+      Math.floor((clock.now().getTime() - Date.parse(transaction.createdAt)) / 1e3)
+    )
+  });
+  server.get(
+    "/api/transactions",
+    { onRequest: tokenHook },
+    operatorHandler(async (request) => {
+      const query = request.query;
+      const limit = parseLimit(query["limit"]);
+      const state = parseText(query["state"]);
+      if (state !== void 0 && !TRANSACTION_STATES.includes(state)) {
+        throw new CommerceError("INPUT_INVALID", `Unknown transaction state "${state}"`, {
+          details: { field: "state" }
+        });
+      }
+      const requestId = parseText(query["requestId"]);
+      const cursor = parseText(query["cursor"]);
+      const page = await journal().listTransactions({
+        ...limit !== void 0 ? { limit } : {},
+        ...parseFlag(query["unresolved"], "unresolved") ? { unresolved: true } : {},
+        ...state !== void 0 ? { state } : {},
+        ...requestId !== void 0 ? { requestId } : {},
+        ...cursor !== void 0 ? { cursor } : {}
+      });
+      return {
+        transactions: page.transactions.map(withAge),
+        ...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {}
+      };
+    })
+  );
+  server.get(
+    "/api/transactions/:id",
+    { onRequest: tokenHook },
+    operatorHandler(async (request) => {
+      const id = request.params.id;
+      const transaction = await journal().getTransaction(id);
+      if (transaction === void 0) {
+        throw new CommerceError("RESOURCE_NOT_FOUND", `Transaction "${id}" was not found`);
+      }
+      const [attempt, receipt, events] = await Promise.all([
+        journal().getPaymentAttempt(transaction.payment.attemptId),
+        transaction.receiptId !== void 0 ? store.getReceipt(transaction.receiptId) : void 0,
+        store.listEvents({ requestId: transaction.requestId, limit: TRANSACTION_EVENT_LIMIT })
+      ]);
+      return {
+        transaction: withAge(transaction),
+        ...attempt !== void 0 ? { attempt } : {},
+        ...receipt !== void 0 ? { receipt } : {},
+        events
+      };
+    })
+  );
+  server.post(
+    "/api/payment-attempts/:id/resolve",
+    { onRequest: tokenHook, bodyLimit: RESOLVE_BODY_LIMIT_BYTES },
+    operatorHandler(async (request) => {
+      const result = await resolveManually({
+        store,
+        authorizationProviders: options.authorizationProviders,
+        clock,
+        logger: options.logger,
+        attemptId: request.params.id,
+        ...parseResolveBody(request.body)
+      });
+      if (!result.resolved) {
+        throw new CommerceError("INPUT_INVALID", result.message, {
+          httpStatus: 409,
+          details: { reason: result.refusal, attemptStatus: result.attempt.status }
+        });
+      }
+      return {
+        attempt: result.attempt,
+        ...result.hold !== void 0 ? { hold: result.hold } : {}
+      };
+    })
+  );
+}
+function parseResolveBody(body) {
+  if (!isRecord(body)) {
+    throw new CommerceError("INPUT_INVALID", "The request body must be a JSON object");
+  }
+  const field = (name, type, required) => {
+    const value = body[name];
+    if (value === void 0 && required || value !== void 0 && typeof value !== type) {
+      throw new CommerceError("INPUT_INVALID", `Field "${name}" must be a ${type}`, {
+        details: { field: name }
+      });
+    }
+  };
+  const unknownField = Object.keys(body).find((name) => !RESOLVE_FIELDS.includes(name));
+  if (unknownField !== void 0) {
+    throw new CommerceError("INPUT_INVALID", `Unknown field "${unknownField}"`, {
+      details: { field: unknownField }
+    });
+  }
+  field("status", "string", true);
+  field("actor", "string", true);
+  field("reason", "string", true);
+  field("externalReference", "string", false);
+  field("confirmExpired", "boolean", false);
+  return body;
 }
 var bodyDigests = /* @__PURE__ */ new WeakMap();
 function digestingStream(request) {
@@ -3803,13 +4228,10 @@ function digestingStream(request) {
     }
   });
 }
-function ledgerHandler(key, list) {
+function operatorHandler(handle) {
   return async (request, reply) => {
     try {
-      const query = request.query;
-      const limit = parseLimit(query["limit"]);
-      const page = await list(limit !== void 0 ? { limit } : {}, query);
-      return { [key]: page };
+      return await handle(request, reply);
     } catch (error) {
       const commerceError = toCommerceError(error);
       reply.status(commerceError.httpStatus).send(toErrorEnvelope(commerceError));
@@ -3817,6 +4239,14 @@ function ledgerHandler(key, list) {
     }
   };
 }
+function ledgerHandler(key, list) {
+  return operatorHandler(async (request) => {
+    const query = request.query;
+    const limit = parseLimit(query["limit"]);
+    const page = await list(limit !== void 0 ? { limit } : {}, query);
+    return { [key]: page };
+  });
+}
 async function handleInvoke(request, reply, options) {
   const resourceId = request.params.id;
   let paymentMethod;
@@ -3997,6 +4427,10 @@ function parseLimit(value) {
   }
   return n;
 }
+function parseText(value) {
+  if (Array.isArray(value)) return parseText(value[0]);
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
 function parseFlag(value, field) {
   if (Array.isArray(value)) return parseFlag(value[0], field);
   if (value === void 0 || value === "false") return false;
@@ -4258,21 +4692,20 @@ var A2A_CALL_SHAPE = 'one data part {"resource": "<skill id>", "input": {...}}';
 function userRoleProblem(role) {
   return role === A2A_USER_ROLE ? void 0 : `Unsupported message role "${String(role)}": only ${A2A_USER_ROLE} is accepted.`;
 }
-var UnknownRecord = z.record(z.string(), z.unknown());
 var MessageSchema = z.object({
   role: z.string(),
   messageId: z.string().optional(),
-  parts: z.array(UnknownRecord),
+  parts: z.array(z.unknown()),
   taskId: z.string().optional(),
   contextId: z.string().optional(),
-  referenceTaskIds: z.array(z.string()).optional()
+  referenceTaskIds: z.array(z.unknown()).optional()
 });
 var ParamsSchema = z.object({
   message: MessageSchema,
   taskId: z.string().optional(),
   contextId: z.string().optional()
 });
-function invalid(message) {
+function invalid2(message) {
   return new CommerceError("INPUT_INVALID", message);
 }
 function unsupported(message, a2aErrorCode) {
@@ -4313,7 +4746,7 @@ function assertSupportedPart(part) {
     );
   }
   if (!("data" in part)) {
-    throw invalid('Message part carries no "data": send a structured data part.');
+    throw invalid2('Message part carries no "data": send a structured data part.');
   }
   const mediaType = part["mediaType"];
   if (mediaType !== void 0 && mediaType !== A2A_JSON_MEDIA_TYPE) {
@@ -4326,21 +4759,21 @@ function assertSupportedPart(part) {
 function parseInvocation(rawParams) {
   const parsed = ParamsSchema.safeParse(rawParams);
   if (!parsed.success) {
-    throw invalid(
+    throw invalid2(
       'Request must carry a "message" with a "role" and a "parts" array of structured data parts.'
     );
   }
   const params = parsed.data;
   const message = params.message;
   if (message.messageId === void 0 || message.messageId.length === 0) {
-    throw invalid('Message must carry a non-empty "messageId".');
+    throw invalid2('Message must carry a non-empty "messageId".');
   }
   const messageId = message.messageId;
   assertNoContinuation(params);
   const roleProblem = userRoleProblem(message.role);
-  if (roleProblem !== void 0) throw invalid(roleProblem);
+  if (roleProblem !== void 0) throw invalid2(roleProblem);
   if (message.parts.length === 0) {
-    throw invalid("Message carries no parts: send exactly one structured data part.");
+    throw invalid2("Message carries no parts: send exactly one structured data part.");
   }
   if (message.parts.length > 1) {
     throw unsupported(
@@ -4348,22 +4781,23 @@ function parseInvocation(rawParams) {
     );
   }
   const part = message.parts[0];
-  if (part === void 0) throw invalid("Message carries no parts.");
+  if (part === void 0) throw invalid2("Message carries no parts.");
+  if (!isRecord(part)) throw invalid2("Message part must be a JSON object.");
   assertSupportedPart(part);
   const data = part["data"];
   if (!isRecord(data)) {
-    throw invalid('Message part "data" must be a JSON object.');
+    throw invalid2('Message part "data" must be a JSON object.');
   }
   const resourceId = data["resource"];
   if (typeof resourceId !== "string") {
-    throw invalid('Message part data must carry a "resource" string naming a canonical resource.');
+    throw invalid2('Message part data must carry a "resource" string naming a canonical resource.');
   }
   if (resourceId.length === 0) {
-    throw invalid('Message part data "resource" must not be empty.');
+    throw invalid2('Message part data "resource" must not be empty.');
   }
   const rawInput = data["input"];
   if (rawInput !== void 0 && !isRecord(rawInput)) {
-    throw invalid('Message part data "input" must be a JSON object.');
+    throw invalid2('Message part data "input" must be a JSON object.');
   }
   return { resourceId, input: rawInput ?? {}, messageId };
 }
@@ -5273,10 +5707,10 @@ function writeAcpFailure(res, failure, headers = {}) {
   writeAcpJson(res, failure.status, failure.error, headers);
 }
 function operationKey(scope) {
-  return sha256(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
+  return sha2562(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
 }
 function requestFingerprint(body) {
-  return sha256(canonicalize(body));
+  return sha2562(canonicalize(body));
 }
 function canonicalize(value) {
   if (value === null) return "null";
@@ -5287,7 +5721,7 @@ function canonicalize(value) {
   }
   return JSON.stringify(value) ?? "null";
 }
-function sha256(value) {
+function sha2562(value) {
   return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
@@ -10002,12 +10436,12 @@ var AcpProtocolAdapter = class {
       mountPath: this.mountPath,
       ...this.discoveryMetadata !== void 0 ? { metadata: this.discoveryMetadata } : {}
     });
-    const invalid2 = validateAcpDocument("discoveryResponse", document);
-    if (invalid2 !== void 0) {
+    const invalid3 = validateAcpDocument("discoveryResponse", document);
+    if (invalid3 !== void 0) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `ACP discovery document does not conform to the ${this.descriptor.supportedSpec} snapshot at "${invalid2.path ?? "$"}" (${invalid2.code}) - check protocols.acp.discovery`,
-        { details: { path: invalid2.path ?? "$", code: invalid2.code } }
+        `ACP discovery document does not conform to the ${this.descriptor.supportedSpec} snapshot at "${invalid3.path ?? "$"}" (${invalid3.code}) - check protocols.acp.discovery`,
+        { details: { path: invalid3.path ?? "$", code: invalid3.code } }
       );
     }
     const exposed = new Map(
@@ -10314,7 +10748,8 @@ function receiptToRow(receipt) {
     duration_ms: receipt.durationMs ?? null,
     protocol: receipt.protocol ?? null,
     metadata_json: receipt.metadata !== void 0 ? JSON.stringify(redact(receipt.metadata)) : null,
-    authorization_json: receipt.authorization !== void 0 ? JSON.stringify(redact(receipt.authorization)) : null
+    authorization_json: receipt.authorization !== void 0 ? JSON.stringify(redact(receipt.authorization)) : null,
+    transaction_id: receipt.transactionId ?? null
   };
 }
 function rowToReceipt(row) {
@@ -10331,7 +10766,8 @@ function rowToReceipt(row) {
     ...row.duration_ms !== null ? { durationMs: row.duration_ms } : {},
     ...row.protocol !== null ? { protocol: row.protocol } : {},
     ...metadata !== void 0 ? { metadata } : {},
-    ...authorization !== void 0 ? { authorization } : {}
+    ...authorization !== void 0 ? { authorization } : {},
+    ...row.transaction_id !== null ? { transactionId: row.transaction_id } : {}
   };
 }
 function eventToRow(event) {
@@ -10345,7 +10781,8 @@ function eventToRow(event) {
     payment_provider: event.paymentProvider ?? null,
     duration_ms: event.durationMs ?? null,
     status: event.status ?? null,
-    data_json: event.data !== void 0 ? JSON.stringify(redact(event.data)) : null
+    data_json: event.data !== void 0 ? JSON.stringify(redact(event.data)) : null,
+    transaction_id: event.transactionId ?? null
   };
 }
 function rowToEvent(row) {
@@ -10360,7 +10797,8 @@ function rowToEvent(row) {
     ...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 } : {}
+    ...data !== void 0 ? { data } : {},
+    ...row.transaction_id !== null ? { transactionId: row.transaction_id } : {}
   };
 }
 function rowToPaymentAttempt(row) {
@@ -10378,7 +10816,61 @@ function rowToPaymentAttempt(row) {
     ...row.external_reference !== null ? { externalReference: row.external_reference } : {},
     ...row.rejection_reason !== null ? { rejectionReason: row.rejection_reason } : {},
     createdAt: row.created_at,
-    updatedAt: row.updated_at
+    updatedAt: row.updated_at,
+    ...row.transaction_id !== null ? { transactionId: row.transaction_id } : {},
+    ...row.resolution_json !== null ? { resolution: JSON.parse(row.resolution_json) } : {}
+  };
+}
+function rowToTransaction(row, now) {
+  const status = row.payment_status;
+  const backend = row.backend_dispatched_at !== null && row.backend_deadline_at !== null ? {
+    dispatchedAt: row.backend_dispatched_at,
+    deadlineAt: row.backend_deadline_at,
+    ...row.backend_status !== null ? { status: row.backend_status } : {},
+    ...row.backend_error_code !== null ? { errorCode: row.backend_error_code } : {}
+  } : void 0;
+  const completedAt = row.completed_at ?? void 0;
+  const authorization = row.authorization_json !== null && row.reservation_id !== null ? {
+    ...JSON.parse(row.authorization_json),
+    reservationId: row.reservation_id
+  } : void 0;
+  return {
+    id: row.id,
+    requestId: row.request_id,
+    resourceId: row.resource_id,
+    protocol: row.protocol,
+    state: transactionState(
+      {
+        payment: { status },
+        ...backend !== void 0 ? { backend } : {},
+        ...completedAt !== void 0 ? { completedAt } : {}
+      },
+      now
+    ),
+    payment: {
+      provider: row.provider,
+      attemptId: row.attempt_id,
+      replayKey: row.replay_key,
+      status,
+      amount: row.payment_amount,
+      currency: row.payment_currency,
+      ...row.network !== null ? { network: row.network } : {},
+      ...row.asset !== null ? { asset: row.asset } : {},
+      ...row.payment_payee !== null ? { payee: row.payment_payee } : {},
+      ...row.payment_external_reference !== null ? { externalReference: row.payment_external_reference } : {},
+      ...row.locator_json !== null ? { locator: JSON.parse(row.locator_json) } : {},
+      ...row.settling_at !== null ? { settlingAt: row.settling_at } : {},
+      ...row.expires_at !== null ? { expiresAt: row.expires_at } : {}
+    },
+    ...authorization !== void 0 ? { authorization } : {},
+    ...backend !== void 0 ? { backend } : {},
+    ...row.receipt_id !== null ? { receiptId: row.receipt_id } : {},
+    ...row.input_digest !== null ? { inputDigest: row.input_digest } : {},
+    configDigest: row.config_digest,
+    ...row.persistence_failures_json !== null ? { persistenceFailures: JSON.parse(row.persistence_failures_json) } : {},
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    ...completedAt !== void 0 ? { completedAt } : {}
   };
 }
 
@@ -10473,13 +10965,60 @@ var MIGRATIONS = [
         CREATE INDEX IF NOT EXISTS idx_payment_attempt_history_request_id ON payment_attempt_history(request_id);
       `);
     }
+  },
+  {
+    version: 4,
+    up(db) {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS transactions (
+          seq                        INTEGER PRIMARY KEY AUTOINCREMENT,
+          id                         TEXT NOT NULL UNIQUE,
+          request_id                 TEXT NOT NULL,
+          resource_id                TEXT NOT NULL,
+          protocol                   TEXT NOT NULL,
+          state                      TEXT NOT NULL,
+          provider                   TEXT NOT NULL,
+          attempt_id                 TEXT NOT NULL,
+          replay_key                 TEXT NOT NULL,
+          network                    TEXT,
+          asset                      TEXT,
+          authorization_json         TEXT,
+          reservation_id             TEXT,
+          locator_json               TEXT,
+          expires_at                 TEXT,
+          input_digest               TEXT,
+          config_digest              TEXT NOT NULL,
+          settling_at                TEXT,
+          backend_dispatched_at      TEXT,
+          backend_deadline_at        TEXT,
+          backend_status             INTEGER,
+          backend_error_code         TEXT,
+          receipt_id                 TEXT,
+          persistence_failures_json  TEXT,
+          completed_at               TEXT,
+          created_at                 TEXT NOT NULL,
+          updated_at                 TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_transactions_state_seq ON transactions(state, seq);
+        CREATE INDEX IF NOT EXISTS idx_transactions_request_id ON transactions(request_id);
+        CREATE INDEX IF NOT EXISTS idx_transactions_replay_key ON transactions(replay_key);
+
+        ALTER TABLE receipts ADD COLUMN transaction_id TEXT;
+        ALTER TABLE events ADD COLUMN transaction_id TEXT;
+        ALTER TABLE payment_attempts ADD COLUMN transaction_id TEXT;
+        ALTER TABLE payment_attempts ADD COLUMN resolution_json TEXT;
+        ALTER TABLE payment_attempt_history ADD COLUMN transaction_id TEXT;
+        ALTER TABLE payment_attempt_history ADD COLUMN resolution_json TEXT;
+        CREATE INDEX IF NOT EXISTS idx_payment_attempt_history_id ON payment_attempt_history(id);
+      `);
+    }
   }
 ];
 var SCHEMA_VERSION2 = MIGRATIONS.at(-1)?.version ?? 0;
-function migrate2(db) {
+function migrate2(db, target = SCHEMA_VERSION2) {
   const current = db.pragma("user_version", { simple: true });
   for (const migration of MIGRATIONS) {
-    if (migration.version <= current) continue;
+    if (migration.version <= current || migration.version > target) continue;
     const apply = db.transaction(() => {
       migration.up(db);
       db.pragma(`user_version = ${migration.version}`);
@@ -10497,6 +11036,22 @@ function clampListLimit(limit) {
 }
 var UNDELIVERED = "backend_status NOT BETWEEN 200 AND 299";
 var UNCERTAIN = "status IN ('settlement-uncertain', 'failed')";
+var TRANSACTION_SELECT = `
+  SELECT t.*,
+    COALESCE(a.status, h.status) AS payment_status,
+    COALESCE(a.amount, h.amount) AS payment_amount,
+    COALESCE(a.currency, h.currency) AS payment_currency,
+    COALESCE(a.payee, h.payee) AS payment_payee,
+    COALESCE(a.external_reference, h.external_reference) AS payment_external_reference
+  FROM transactions t
+  LEFT JOIN payment_attempts a ON a.id = t.attempt_id
+  LEFT JOIN payment_attempt_history h ON a.id IS NULL AND h.seq = (
+    SELECT MAX(seq) FROM payment_attempt_history
+    WHERE replay_key = t.replay_key AND id = t.attempt_id
+  )`;
+var TIME_DEPENDENT = "t.backend_deadline_at IS NOT NULL AND t.completed_at IS NULL";
+var RESOLVED_STATES = ["delivered", "payment-failed"];
+var CURSOR_PATTERN = /^[1-9][0-9]{0,15}$/;
 var defaultIds = {
   next: (prefix) => prefix !== void 0 ? `${prefix}_${randomUUID()}` : randomUUID()
 };
@@ -10512,8 +11067,8 @@ function createSqliteReceiptStore(options) {
   const db = openSqliteDatabase({ path: path2, label: "Receipt database", logger });
   migrate2(db);
   const insertReceiptStmt = db.prepare(
-    `INSERT INTO receipts (id, request_id, resource_id, payment_json, delivered_at, backend_status, duration_ms, protocol, metadata_json, authorization_json)
-     VALUES (@id, @request_id, @resource_id, @payment_json, @delivered_at, @backend_status, @duration_ms, @protocol, @metadata_json, @authorization_json)`
+    `INSERT INTO receipts (id, request_id, resource_id, payment_json, delivered_at, backend_status, duration_ms, protocol, metadata_json, authorization_json, transaction_id)
+     VALUES (@id, @request_id, @resource_id, @payment_json, @delivered_at, @backend_status, @duration_ms, @protocol, @metadata_json, @authorization_json, @transaction_id)`
   );
   const getReceiptStmt = db.prepare("SELECT * FROM receipts WHERE id = ?");
   const listReceiptsStmt = db.prepare(
@@ -10535,8 +11090,8 @@ function createSqliteReceiptStore(options) {
     `SELECT COUNT(*) AS count FROM receipts WHERE ${UNDELIVERED}`
   );
   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)`
+    `INSERT INTO events (id, type, request_id, resource_id, at, adapter, payment_provider, duration_ms, status, data_json, transaction_id)
+     VALUES (@id, @type, @request_id, @resource_id, @at, @adapter, @payment_provider, @duration_ms, @status, @data_json, @transaction_id)`
   );
   const listEventsStmt = db.prepare(
     "SELECT * FROM events ORDER BY at DESC, seq DESC LIMIT ?"
@@ -10545,13 +11100,13 @@ function createSqliteReceiptStore(options) {
     "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)
+    `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, transaction_id)
+     VALUES (@id, @request_id, @resource_id, @provider, @replay_key, @status, @amount, @currency, @payer, @payee, @external_reference, @rejection_reason, @created_at, @updated_at, @transaction_id)
      RETURNING *`
   );
   const archiveRejectedAttemptStmt = db.prepare(
-    `INSERT INTO payment_attempt_history (id, request_id, resource_id, provider, replay_key, status, amount, currency, payer, payee, external_reference, rejection_reason, created_at, updated_at, superseded_at)
-     SELECT id, request_id, resource_id, provider, replay_key, status, amount, currency, payer, payee, external_reference, rejection_reason, created_at, updated_at, @created_at
+    `INSERT INTO payment_attempt_history (id, request_id, resource_id, provider, replay_key, status, amount, currency, payer, payee, external_reference, rejection_reason, created_at, updated_at, superseded_at, transaction_id, resolution_json)
+     SELECT id, request_id, resource_id, provider, replay_key, status, amount, currency, payer, payee, external_reference, rejection_reason, created_at, updated_at, @created_at, transaction_id, resolution_json
      FROM payment_attempts
      WHERE replay_key = @replay_key AND provider = @provider AND status = 'rejected'`
   );
@@ -10559,7 +11114,8 @@ function createSqliteReceiptStore(options) {
     `UPDATE payment_attempts SET id = @id, request_id = @request_id, resource_id = @resource_id,
        status = 'reserved', amount = @amount, currency = @currency,
        payer = @payer, payee = @payee, external_reference = NULL, rejection_reason = NULL,
-       created_at = @created_at, updated_at = @updated_at
+       created_at = @created_at, updated_at = @updated_at,
+       transaction_id = @transaction_id, resolution_json = NULL
      WHERE replay_key = @replay_key AND provider = @provider AND status = 'rejected'
      RETURNING *`
   );
@@ -10568,7 +11124,7 @@ function createSqliteReceiptStore(options) {
        external_reference = COALESCE(@external_reference, external_reference),
        rejection_reason = COALESCE(@rejection_reason, rejection_reason),
        updated_at = @updated_at
-     WHERE replay_key = @replay_key`
+     WHERE replay_key = @replay_key AND resolution_json IS NULL`
   );
   const listPaymentAttemptsStmt = db.prepare(
     "SELECT * FROM payment_attempts ORDER BY created_at DESC, seq DESC LIMIT ?"
@@ -10585,13 +11141,176 @@ function createSqliteReceiptStore(options) {
   const countUncertainPaymentAttemptsStmt = db.prepare(
     `SELECT COUNT(*) AS count FROM payment_attempts WHERE ${UNCERTAIN}`
   );
-  const paymentAttemptStatusStmt = db.prepare(
-    "SELECT status FROM payment_attempts WHERE replay_key = ?"
+  const paymentAttemptStatusStmt = db.prepare("SELECT id, status, resolution_json FROM payment_attempts WHERE replay_key = ?");
+  const insertTransactionStmt = db.prepare(
+    `INSERT INTO transactions (id, request_id, resource_id, protocol, state, provider, attempt_id, replay_key, network, asset, authorization_json, reservation_id, locator_json, expires_at, input_digest, config_digest, created_at, updated_at)
+     VALUES (@id, @request_id, @resource_id, @protocol, @state, @provider, @attempt_id, @replay_key, @network, @asset, @authorization_json, @reservation_id, @locator_json, @expires_at, @input_digest, @config_digest, @created_at, @created_at)`
   );
-  const reclaimRejectedAttempt = db.transaction(
-    (params) => {
-      archiveRejectedAttemptStmt.run(params);
-      return reclaimPaymentAttemptStmt.get(params);
+  const getTransactionStmt = db.prepare(
+    `${TRANSACTION_SELECT} WHERE t.id = ?`
+  );
+  const transactionsOfAttemptStmt = db.prepare(
+    `SELECT t.id FROM payment_attempts a
+     JOIN transactions t ON t.replay_key = a.replay_key AND t.attempt_id = a.id
+     WHERE a.replay_key = ?`
+  );
+  const transactionsOfAttemptIdStmt = db.prepare(
+    `SELECT t.id FROM payment_attempts a
+     JOIN transactions t ON t.replay_key = a.replay_key AND t.attempt_id = a.id
+     WHERE a.id = ?`
+  );
+  const setTransactionStateStmt = db.prepare("UPDATE transactions SET state = ? WHERE id = ?");
+  const stepStmts = {
+    settling: db.prepare(
+      "UPDATE transactions SET settling_at = @at, updated_at = @at WHERE id = @id"
+    ),
+    // A transaction without an authorization has no hold to record
+    hold: db.prepare(
+      `UPDATE transactions SET authorization_json = json_set(authorization_json, '$.hold', @hold), updated_at = @at
+       WHERE id = @id AND authorization_json IS NOT NULL`
+    ),
+    "backend-dispatched": db.prepare(
+      `UPDATE transactions SET backend_dispatched_at = @at, backend_deadline_at = @deadline_at, updated_at = @at
+       WHERE id = @id`
+    ),
+    // Preserve a backend result even when the dispatch step was not saved:
+    // use the result time for missing dispatch and deadline timestamps
+    "backend-result": db.prepare(
+      `UPDATE transactions SET backend_status = @status, backend_error_code = @error_code,
+         backend_dispatched_at = COALESCE(backend_dispatched_at, @at),
+         backend_deadline_at = COALESCE(backend_deadline_at, @at), updated_at = @at
+       WHERE id = @id`
+    ),
+    receipt: db.prepare(
+      "UPDATE transactions SET receipt_id = @receipt_id, updated_at = @at WHERE id = @id"
+    ),
+    completed: db.prepare(
+      `UPDATE transactions SET completed_at = @at, persistence_failures_json = @persistence_failures_json, updated_at = @at
+       WHERE id = @id`
+    )
+  };
+  const getPaymentAttemptStmt = db.prepare(
+    "SELECT * FROM payment_attempts WHERE id = ?"
+  );
+  const getArchivedPaymentAttemptStmt = db.prepare(
+    "SELECT * FROM payment_attempt_history WHERE id = ? ORDER BY seq DESC LIMIT 1"
+  );
+  const resolvePaymentAttemptStmt = db.prepare(
+    `UPDATE payment_attempts SET status = @status,
+       rejection_reason = COALESCE(@rejection_reason, rejection_reason),
+       external_reference = COALESCE(@external_reference, external_reference),
+       resolution_json = @resolution_json, updated_at = @updated_at
+     WHERE id = @id AND status = @expected_status AND resolution_json IS NULL`
+  );
+  function refreshTransactionState(id, now) {
+    const row = getTransactionStmt.get(id);
+    if (row !== void 0) setTransactionStateStmt.run(rowToTransaction(row, now).state, id);
+  }
+  const reserve = db.transaction(
+    (reservation, params) => {
+      let row;
+      if (reservation.reclaimRejected === true) {
+        archiveRejectedAttemptStmt.run(params);
+        row = reclaimPaymentAttemptStmt.get(params);
+      }
+      row ??= insertPaymentAttemptStmt.get({
+        ...params,
+        status: "reserved",
+        external_reference: null,
+        rejection_reason: null
+      });
+      const txn = reservation.transaction;
+      if (txn !== void 0) {
+        const { reservationId, ...authorization } = txn.authorization ?? {};
+        insertTransactionStmt.run({
+          id: txn.id,
+          request_id: reservation.requestId,
+          resource_id: reservation.resourceId,
+          protocol: txn.protocol,
+          state: transactionState({ payment: { status: "reserved" } }, row.created_at),
+          provider: reservation.provider,
+          attempt_id: row.id,
+          replay_key: reservation.replayKey,
+          network: txn.network ?? null,
+          asset: txn.asset ?? null,
+          authorization_json: reservationId !== void 0 ? JSON.stringify(redact({ ...authorization, hold: "reserved" })) : null,
+          reservation_id: reservationId ?? null,
+          locator_json: txn.locator !== void 0 ? JSON.stringify(redact(txn.locator)) : null,
+          expires_at: txn.expiresAt ?? null,
+          input_digest: txn.inputDigest ?? null,
+          config_digest: txn.configDigest,
+          created_at: row.created_at
+        });
+      }
+      return row;
+    }
+  );
+  const updateAttempt = db.transaction((update, now) => {
+    const { changes } = updatePaymentAttemptStmt.run({
+      replay_key: update.replayKey,
+      status: update.status,
+      external_reference: update.externalReference ?? null,
+      rejection_reason: update.rejectionReason ?? null,
+      updated_at: now
+    });
+    for (const { id } of transactionsOfAttemptStmt.all(update.replayKey)) {
+      refreshTransactionState(id, now);
+    }
+    return changes;
+  });
+  const recordStep = db.transaction((step) => {
+    const base = { id: step.transactionId, at: step.at };
+    let changes;
+    switch (step.kind) {
+      case "settling":
+        changes = stepStmts.settling.run(base).changes;
+        break;
+      case "hold":
+        changes = stepStmts.hold.run({ ...base, hold: step.hold }).changes;
+        break;
+      case "backend-dispatched":
+        changes = stepStmts["backend-dispatched"].run({
+          ...base,
+          deadline_at: step.deadlineAt
+        }).changes;
+        break;
+      case "backend-result":
+        changes = stepStmts["backend-result"].run({
+          ...base,
+          status: step.status,
+          error_code: step.errorCode ?? null
+        }).changes;
+        break;
+      case "receipt":
+        changes = stepStmts.receipt.run({ ...base, receipt_id: step.receiptId }).changes;
+        break;
+      case "completed":
+        changes = stepStmts.completed.run({
+          ...base,
+          persistence_failures_json: step.persistenceFailures !== void 0 && step.persistenceFailures.length > 0 ? JSON.stringify(step.persistenceFailures) : null
+        }).changes;
+        break;
+    }
+    if (changes > 0) refreshTransactionState(step.transactionId, step.at);
+    return changes;
+  });
+  const resolveAttempt = db.transaction(
+    (request, now) => {
+      const { changes } = resolvePaymentAttemptStmt.run({
+        id: request.attemptId,
+        expected_status: request.expectedStatus,
+        status: request.status,
+        rejection_reason: request.rejectionReason ?? null,
+        // An operator's reference is unverified; it stays in resolution_json only
+        external_reference: request.resolution.method === "reconcile" ? request.resolution.externalReference ?? null : null,
+        resolution_json: JSON.stringify(redact(request.resolution)),
+        updated_at: now
+      });
+      if (changes === 0) return false;
+      for (const { id } of transactionsOfAttemptIdStmt.all(request.attemptId)) {
+        refreshTransactionState(id, now);
+      }
+      return true;
     }
   );
   let closed = false;
@@ -10600,7 +11319,7 @@ function createSqliteReceiptStore(options) {
     kind: "storage",
     implementationVersion: PACKAGE_VERSION,
     supportedSpec: `sqlite-schema-v${SCHEMA_VERSION2}`,
-    capabilities: ["receipts", "events", "payment-attempts"],
+    capabilities: ["receipts", "events", "payment-attempts", "transactions"],
     status: "stable"
   };
   const store = {
@@ -10640,17 +11359,12 @@ function createSqliteReceiptStore(options) {
         payer: reservation.payer ?? null,
         payee: reservation.payee ?? null,
         created_at: now,
-        updated_at: now
+        updated_at: now,
+        transaction_id: reservation.transaction?.id ?? null
       };
       let row;
       try {
-        row = (reservation.reclaimRejected === true ? reclaimRejectedAttempt.immediate(params) : void 0) ?? // RETURNING on a successful insert always yields the inserted row
-        insertPaymentAttemptStmt.get({
-          ...params,
-          status: "reserved",
-          external_reference: null,
-          rejection_reason: null
-        });
+        row = reserve.immediate(reservation, params);
       } catch (err) {
         if (isUniqueConstraintOn(err, "payment_attempts.replay_key")) {
           const existing = paymentAttemptStatusStmt.get(reservation.replayKey);
@@ -10670,14 +11384,23 @@ function createSqliteReceiptStore(options) {
     },
     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) {
+        if (updateAttempt(update, clock.nowIso()) === 0) {
+          const existing = paymentAttemptStatusStmt.get(update.replayKey);
+          if (existing?.resolution_json != null) {
+            logger.warn(
+              {
+                attemptId: existing.id,
+                resolvedStatus: existing.status,
+                status: update.status,
+                ...update.externalReference !== void 0 ? { externalReference: update.externalReference } : {}
+              },
+              "receipt-store: payment attempt already resolved; update not applied"
+            );
+            throw new CommerceError(
+              "STORAGE_ERROR",
+              `Payment attempt ${existing.id} is already resolved; the update was not applied`
+            );
+          }
           throw new CommerceError(
             "STORAGE_ERROR",
             `No payment attempt found for replayKey=${update.replayKey}`
@@ -10729,6 +11452,74 @@ function createSqliteReceiptStore(options) {
       const rows = listOptions.requestId !== void 0 ? (uncertain ? listUncertainPaymentAttemptsByRequestStmt : listPaymentAttemptsByRequestStmt).all(listOptions.requestId, limit) : (uncertain ? listUncertainPaymentAttemptsStmt : listPaymentAttemptsStmt).all(limit);
       return rows.map(rowToPaymentAttempt);
     },
+    async recordTransactionStep(step) {
+      try {
+        if (recordStep(step) === 0) {
+          throw new CommerceError(
+            "STORAGE_ERROR",
+            step.kind === "hold" ? `No transaction with an authorization hold found for transactionId=${step.transactionId}` : `No transaction found for transactionId=${step.transactionId}`
+          );
+        }
+      } catch (err) {
+        throw toCommerceError(err, "STORAGE_ERROR", "Failed to record transaction step");
+      }
+    },
+    async getTransaction(id) {
+      const row = getTransactionStmt.get(id);
+      return row !== void 0 ? rowToTransaction(row, clock.nowIso()) : void 0;
+    },
+    async listTransactions(listOptions = {}) {
+      const { cursor, state, unresolved, pendingHold, requestId } = listOptions;
+      if (cursor !== void 0 && !CURSOR_PATTERN.test(cursor)) {
+        throw new CommerceError("INPUT_INVALID", "Malformed transaction list cursor");
+      }
+      const limit = clampListLimit(listOptions.limit);
+      const where = [];
+      const params = [];
+      if (cursor !== void 0) {
+        where.push("t.seq < ?");
+        params.push(Number(cursor));
+      }
+      if (requestId !== void 0) {
+        where.push("t.request_id = ?");
+        params.push(requestId);
+      }
+      if (state !== void 0) {
+        where.push(`(t.state = ? OR (${TIME_DEPENDENT}))`);
+        params.push(state);
+      }
+      if (pendingHold === true) {
+        where.push("json_extract(t.authorization_json, '$.hold') IN ('reserved', 'uncertain')");
+      }
+      if (unresolved === true) {
+        where.push(`t.state NOT IN (${RESOLVED_STATES.map(() => "?").join(", ")})`);
+        params.push(...RESOLVED_STATES);
+      }
+      const rows = db.prepare(
+        `${TRANSACTION_SELECT}${where.length > 0 ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY t.seq DESC LIMIT ?`
+      ).all(...params, limit);
+      const now = clock.nowIso();
+      const resolved = RESOLVED_STATES;
+      const transactions = rows.map((row) => rowToTransaction(row, now)).filter(
+        (t) => (state === void 0 || t.state === state) && (unresolved !== true || !resolved.includes(t.state))
+      );
+      const last = rows.at(-1);
+      return {
+        transactions,
+        ...rows.length === limit && last !== void 0 ? { nextCursor: String(last.seq) } : {}
+      };
+    },
+    async getPaymentAttempt(id) {
+      const row = getPaymentAttemptStmt.get(id) ?? getArchivedPaymentAttemptStmt.get(id);
+      return row !== void 0 ? rowToPaymentAttempt(row) : void 0;
+    },
+    async resolvePaymentAttempt(request) {
+      try {
+        return resolveAttempt(request, clock.nowIso());
+      } catch (err) {
+        throw toCommerceError(err, "STORAGE_ERROR", "Failed to resolve payment attempt");
+      }
+    },
     descriptor,
     async health() {
       const startedAt = clock.monotonicMs();