portage-ucp 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ce343c7abccfbe4c1a8cf2ed0db6340d588c770e959fef42aec644ef6a69800
-  data.tar.gz: 7d1a96bb2e150b822c1dedbe95b8b3f14fbced7d6be9b5287e120e3e8152059f
+  metadata.gz: 11276545531e50962e8e16e8d1c966853adfa8ddb8c1aa3851f7fa89a494b33e
+  data.tar.gz: 7421a957575b40d55200ce54e70335bec9a7c7a735cd0941eb2e1bdec0bdd535
 SHA512:
-  metadata.gz: 0cd44b69ef19d804c91696b6477e3616eb9dd64c326754f5ff7f142ff494bdaf42b1bd4686888dcb1d7c6e6198b737cc501384278a9a6d2441173b6191029eab
-  data.tar.gz: 22a096bb7ab8cfaa6285ad12b8c5dfd8098c40f4f538115688e03ad5eac59273f16eca247d1409e28f8f30c730d9ef7cb7c7a5d19586bdacb0c0f002f0b61e9a
+  metadata.gz: 52d85b70ca4e16311c318331bb0ca161c82ff9f833e4d08b5c3e262550ecaeccf334aaf35cf5e39f5a351e3a5aa58ed0a508615003c1da6d54d728a9dc34eda9
+  data.tar.gz: 05e158b1864ae760e08ddb3ab76080a1effd59bfa475ebd64e23f0f2e30f6ff87b4afe44eef0112ca5dda0a6e579e64532df396743cab582373f90e44805b089

data/CHANGELOG.md

@@ -4,6 +4,119 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [Unreleased]
+
+## [0.5.0] - 2026-09-14
+
+- Added `Adapter#create_payment_enrollment(idempotency_key:)` /
+  `#get_payment_enrollment(enrollment_id:)`, advertised as a new
+  `app.portage-ucp.payment_enrollment` capability — a Portage extension, not
+  part of the UCP spec. Starts a card-on-file enrollment without the card
+  ever touching this process: `#create_payment_enrollment` returns a
+  gateway-hosted `setup_url`, and the caller polls `#get_payment_enrollment`
+  until `status` leaves `"pending"` and a `payment_token` appears.
+  Implemented in `ReferenceAdapter` as a worked example (docs/plans/agentic-payments.md
+  Phase 1).
+- Made the idempotency dedup store pluggable — `Support::Idempotency` now
+  takes a `store:` (defaulting to the existing in-memory behavior via the new
+  `MemoryStore`), with a `FileStore` alternative for dedup that survives a
+  process restart.
+- Added a durable `Support::TransactionLog`, wired into
+  `Dispatcher#complete_checkout` dispatch — a transaction is reserved before
+  dispatch and marked settled/failed after, so a crash mid-charge leaves a
+  diagnosable record instead of silence.
+- Extended `TransactionLog` to also record policy decisions and confirmation
+  outcomes on the same transaction record `PolicyGuard`/`Confirmer` gate.
+- Added `PolicyGuard`, wired into `Dispatcher` just before `complete_checkout`
+  dispatch — enforces `Policy`'s per-transaction/rolling caps, velocity, and
+  merchant allowlist (docs/plans/agentic-payments.md Phase 2). Configured via
+  `portage-cli`'s `portage policy show/set`.
+- Added per-token enrollment scopes to `Policy` — a merchant/max-amount/
+  currency scope can be bound to a token at enrollment time and is checked by
+  `PolicyGuard` keyed by the same `token_ref` derived from the token at
+  charge time.
+- Added a `Confirmer` interface, wired into `Dispatcher` right after
+  `PolicyGuard.check!` passes and before `complete_checkout` dispatch.
+  `Confirmer::Terminal` blocks the process on stdin and fails closed on
+  anything but an explicit `"y"` (no answer, `"n"`, or EOF all deny);
+  `Confirmer::AutoApprove` is for specs/conformance kits (docs/plans/agentic-payments.md
+  Phase 3).
+- Added a durable `Support::OrderLedger`, wired into the `complete_checkout`
+  settle path — written after the transaction record is already complete, so
+  a failed snapshot write surfaces without flipping an already-settled charge
+  to failed.
+- `Mcp::Server.call_tool` now extracts `ucp-agent.profile` from `_meta` the
+  same way it already does `correlation_id` from `traceparent`, logging/
+  forwarding it as `agent_profile` through every transport (http, stdio,
+  loopback) and `Client::Session`. Additive only — `Dispatcher` accepts and
+  threads it without yet acting on it.
+- Added `Adapter#lookup_catalog(ids:)`, advertised alongside `search_catalog`
+  — fetches several known product ids in one round trip instead of one
+  `get_product` call per id. Implemented in `Shopify::Adapter` via the Admin
+  API's `nodes(ids:)` field, reusing the same `Mapper.product` shape
+  `get_product`/`search_catalog` already use.
+
+## [0.4.0] - 2026-08-28
+
+- Added `Adapter#reorder(order_id:, idempotency_key:)`, advertised as a new
+  `app.portage-ucp.reorder` capability — a Portage extension, not part of the
+  UCP spec. Hydrates a `Cart` from a previous order's line items, re-checking
+  each item's current price/availability rather than replaying the order's
+  historical totals, and reports anything no longer purchasable via the new
+  `ReorderResult#unavailable_items` rather than failing the whole call.
+  Implemented in `ReferenceAdapter` as a worked example.
+- `Mcp::Server.call_tool` now emits a minimal pre-auth `tool_call_received`
+  event (capability, action, correlation id — no arguments) before
+  `authorize`/`rate_limit` run, moving the full `tool_called` event
+  (arguments included) below them. Previously the full event, arguments and
+  all, was logged before authorization, so an unauthenticated caller could
+  write attacker-chosen content into the operator's logs at whatever volume
+  the rate limiter would otherwise have refused (design-log §23).
+- `Mcp::Server.correlation_id_for` stamps both events with a correlation id
+  read from the inbound W3C `traceparent` in `server_context[:_meta]`
+  (SEP-414, `MCP::TraceContext`), falling back to `SecureRandom.uuid` when
+  absent or malformed. Deliberately per-request, not per-session —
+  `Server::Context` is built once per process in `.build`, and `mcp`
+  0.25.0's Streamable HTTP transport is stateful and multi-session, so
+  memoizing an id there would stamp every session in the process with the
+  same value (design-log §23). Because `traceparent` is unauthenticated
+  input read before `authorize`/`rate_limit` run, it's validated against
+  the W3C Trace Context format before use rather than accepted as-is — a
+  malformed or oversized value falls back to a generated id instead of
+  reaching the pre-auth log or `Dispatcher`/`CheckoutState` unchecked.
+- `Dispatcher` now threads its logger and each call's correlation id to the
+  adapter for the duration of that one call
+  (`Support::CheckoutState.with_observability`) so a
+  `checkout_state_transition` event (§12) fires from `record_checkout_status`
+  carrying the same correlation id as the `tool_called` event that triggered
+  it — without adding a `correlation_id:` kwarg to any checkout method, which
+  would have been a breaking change to the `Adapter` contract. Storage is
+  `Thread.current`, keyed per adapter object and restored on exit, rather
+  than an instance variable on the adapter: `Mcp::Server.build` constructs
+  one adapter per process, shared across every concurrent session, so an
+  instance variable would let two in-flight requests clobber each other's
+  correlation id — the same per-process-state trap §23 diagnosed for the
+  correlation id generator itself, one layer down. No `capability_negotiated`
+  event yet: `CapabilityNegotiator#negotiate` has no call site anywhere in
+  the gem outside its own spec, so there's nowhere to emit it from without
+  building that call site first (design-log §23).
+- `Observability::REDACTED_KEYS` grows past the three credential keys to
+  cover the PII that actually flows through logged events — `email`
+  (`Identity`, §3) and `first_name`/`last_name`/`phone_number`/
+  `street_address`/`extended_address`/`address_locality`/`address_region`/
+  `address_country`/`postal_code` (`PostalAddress`, fulfillment
+  destinations). §12's "Money-adjacent PII" named no real key — `Money`/
+  `Total` carry only amounts and currency codes (design-log §23 step 4).
+- `Rack::WebhookEndpoint` takes a `logger:` kwarg (defaulting to
+  `Portage::Ucp.configuration.logger`) and emits `order_webhook_received`
+  (order id, checkout id) on a verified payload and `order_webhook_rejected`
+  (reason: `invalid_signature` or `bad_request`) on the two rejection paths
+  — never the request body. No new `config.event_sink`: this endpoint is a
+  plain Rack app never built through `Mcp::Server.build`, so it can't reach
+  `mcp`'s own request hooks, and threading the gem's existing `logger:`
+  convention through one more constructor was the whole fix (design-log
+  §23 step 5).
+
 ## [0.3.0] - 2026-08-27
 
 - `Portage::Ucp::Support::Retry` (`lib/portage/ucp/support/retry.rb`) —

data/README.md

@@ -25,6 +25,10 @@ in this gem.
 | `Portage::Ucp::Rack::WebhookEndpoint` | HMAC-verified inbound order-lifecycle webhooks. |
 | `Portage::Ucp::SchemaValidator` | Validates data against UCP's own vendored JSON Schemas/OpenRPC docs, offline. |
 | `Portage::Ucp::Resolver` / `exe/portage-ucp-check` | Probes any store's homepage/`.well-known/ucp` and recommends the matching adapter gem. |
+| `Portage::Ucp::Support::TransactionLog` | Durable pre/post-dispatch record of every `complete_checkout` call — reserved before dispatch, marked settled/failed after, so a crash mid-charge is diagnosable rather than silently lost. |
+| `Portage::Ucp::Support::OrderLedger` | Durable snapshot written after settlement, alongside (not instead of) the transaction record — a failed snapshot write surfaces without flipping an already-settled charge to failed. |
+| `Portage::Ucp::Confirmer` | Gate run just before `complete_checkout` dispatch, after `PolicyGuard`. `Confirmer::Terminal` blocks on stdin and fails closed on anything but an explicit `"y"`; `Confirmer::AutoApprove` is for specs/conformance kits that need a real `confirm!` without blocking. |
+| `Portage::Ucp::PolicyGuard` / `Portage::Ucp::Policy` | Per-transaction/rolling/velocity caps and a merchant allowlist, checked before `complete_checkout` dispatch; configured via `portage-cli`'s `portage policy show/set`. |
 
 Security defaults are all locked down, not permissive-by-omission —
 `UnconfiguredAuthenticator` rejects every mutating call until you configure a real

data/lib/portage/ucp/adapter.rb

@@ -10,6 +10,11 @@ module Portage
       # get_cart/get_checkout/get_order.
       # @return [Portage::Ucp::ProductDetail, nil]
       def get_product(product_id:) = not_implemented
+      # Batch fetch — same result shape as search_catalog, for a caller that
+      # already has a set of product ids (e.g. hydrating a cart/order) and
+      # wants one round trip instead of N #get_product calls.
+      # @return [Portage::Ucp::CatalogSearchResult]
+      def lookup_catalog(product_ids:) = not_implemented
 
       # --- Cart (dev.ucp.shopping.cart) ---
       # Full-replacement semantics, matching UCP's real cart methods: create/
@@ -90,6 +95,19 @@ module Portage
       # @return [Portage::Ucp::Order]
       def refund_order(order_id:, line_items:, idempotency_key:, reason: nil) = not_implemented
 
+      # --- Reorder (app.portage-ucp.reorder — Portage extension, not part of
+      # the UCP spec: dev.ucp.dev has no reorder/cart-hydration capability as
+      # of the 2026-04-08 spec) ---
+      # Hydrates a cart from a previous order's line items so a caller doesn't
+      # have to re-walk get_order + create_cart itself. Re-checks each item's
+      # current price/availability rather than replaying the order's snapshot
+      # totals — order_line_item.json's totals are historical, not live, same
+      # posture as complete_checkout's stock re-check above — and drops
+      # anything no longer purchasable instead of failing the whole call,
+      # reporting what got dropped via ReorderResult#unavailable_items.
+      # @return [Portage::Ucp::ReorderResult, nil] nil if the order isn't found.
+      def reorder(order_id:, idempotency_key:) = not_implemented
+
       # --- Discount (dev.ucp.shopping.discount) ---
       # Extends Cart/Checkout with the `discount_codes:` param above rather
       # than adding actions of its own — Capability::DISCOUNT advertises off
@@ -110,6 +128,18 @@ module Portage
       # @return [Portage::Ucp::Identity] linked profile for an exchanged OAuth token
       def link_identity(oauth_token:) = not_implemented
 
+      # --- Payment Enrollment (app.portage-ucp.payment_enrollment — Portage
+      # extension, not part of the UCP spec) ---
+      # Starts a card-on-file enrollment. Card data never touches this
+      # process: #create_payment_enrollment returns a `setup_url` for a
+      # gateway-hosted page where the human enters their card, and the
+      # caller polls #get_payment_enrollment until `status` leaves
+      # "pending". See docs/plans/agentic-payments.md Phase 1.
+      # @return [Portage::Ucp::PaymentEnrollment]
+      def create_payment_enrollment(idempotency_key:) = not_implemented
+      # @return [Portage::Ucp::PaymentEnrollment, nil] nil if the enrollment isn't found
+      def get_payment_enrollment(enrollment_id:) = not_implemented
+
       private
 
       def not_implemented

data/lib/portage/ucp/capabilities/catalog.rb

@@ -4,7 +4,8 @@ module Portage
       CATALOG = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.catalog",
         version: "1",
-        actions: { "search_catalog" => :search_catalog, "get_product" => :get_product }
+        actions: { "search_catalog" => :search_catalog, "get_product" => :get_product,
+                   "lookup_catalog" => :lookup_catalog }
       )
     end
   end

data/lib/portage/ucp/capabilities/identity_linking.rb

@@ -7,7 +7,8 @@ module Portage
         actions: { "link_identity" => :link_identity }
       )
 
-      ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT].freeze
+      ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT, REORDER,
+             PAYMENT_ENROLLMENT].freeze
     end
   end
 end

data/lib/portage/ucp/capabilities/payment_enrollment.rb

@@ -0,0 +1,17 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extension, not part of the UCP spec (no ucp.dev
+      # reverse-domain meaning to borrow), same posture as Capabilities::REORDER.
+      # Advertised only if the adapter overrides Adapter#create_payment_enrollment
+      # — an adapter with no real gateway support for it simply never shows it
+      # in the manifest (see docs/plans/agentic-payments.md Phase 1).
+      PAYMENT_ENROLLMENT = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.payment_enrollment",
+        version: "1",
+        actions: { "create_payment_enrollment" => :create_payment_enrollment,
+                  "get_payment_enrollment" => :get_payment_enrollment }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capabilities/reorder.rb

@@ -0,0 +1,17 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extension, not part of the UCP spec (no ucp.dev
+      # reverse-domain meaning to borrow), so this is namespaced under the
+      # gem's own name instead of "dev.ucp.*". Advertised only if the
+      # adapter overrides Adapter#reorder, same as every other capability
+      # (Capability#advertised_for?) — an adapter that hasn't implemented it
+      # simply never shows it in the manifest.
+      REORDER = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.reorder",
+        version: "1",
+        actions: { "reorder" => :reorder }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capability_negotiator.rb

@@ -13,6 +13,36 @@ module Portage
     # params instead. Either way this class only deals in the parsed version
     # list — transports are responsible for extracting it from their own
     # request shape.
+    #
+    # §23 step 3: §12 promises a `capability_negotiated` event here, but
+    # #negotiate has no call site anywhere in this gem outside its own spec
+    # — nothing in the request path (transport `initialize` handling, or
+    # otherwise) invokes it yet. Wiring the event would mean building that
+    # call site first, which is a bigger change than threading a logger
+    # through an existing collaborator; left undone, and cut from §12
+    # rather than promised.
+    #
+    # §25: the reason there's no call site is structural, not just
+    # unbuilt. `mcp` 0.25.0's `MCP::Server#init`
+    # (lib/mcp/server.rb:608) never reads `params[:_meta]` and never calls
+    # `add_instrumentation_data`, unlike `call_tool` — so nothing at
+    # initialize time reaches `around_request`/`instrumentation_callback`
+    # or the `_meta` mechanism `Mcp::Server.correlation_id_for` already
+    # relies on (§23/§24). And over HTTP,
+    # `StreamableHTTPTransport#handle_initialization`
+    # (lib/mcp/server/transports/streamable_http_transport.rb:812) builds
+    # a `Rack::Request` with full headers but only pulls `HTTP_ORIGIN` out
+    # of it before handing the raw JSON body string to
+    # `ServerSession#handle_json` — a `UCP-Agent` header never crosses into
+    # the server at all. Wiring #negotiate for real means monkeypatching
+    # both (subclass/prepend `MCP::Server#init` to capture
+    # `clientInfo`/`_meta`, and `StreamableHTTPTransport#handle_initialization`
+    # to capture the `UCP-Agent` header), coupling this gem to `mcp`
+    # internals that could silently break on a `mcp` gem upgrade.
+    # Revisiting this needs either an upstream `mcp` gem hook at
+    # initialize time, or a deliberate decision to accept the monkeypatch
+    # coupling — not something to build silently as a side effect of
+    # another task.
     class CapabilityNegotiator
       def initialize(registry: CapabilityRegistry.default)
         @registry = registry

data/lib/portage/ucp/confirmer.rb

@@ -0,0 +1,74 @@
+require "timeout"
+
+module Portage
+  module Ucp
+    # Phase 3 (docs/plans/agentic-payments.md) — the last gate before a
+    # payment-completing dispatch, run by Dispatcher right after PolicyGuard
+    # passes. Transport-agnostic by design: Dispatcher only ever calls
+    # `#confirm!(amount:, currency:, merchant:, idempotency_key:)` on
+    # whatever object it's given, so a future WhatsApp/Slack confirmer is a
+    # separate gem implementing the same method, no core change required.
+    # `idempotency_key` rides along even though this phase's Terminal
+    # implementation ignores it — an async transport needs it to bind a
+    # reply back to the request that asked.
+    module Confirmer
+      # Blocks the CLI process on stdin: "Approve? [y/N]". Fail-closed — no
+      # answer within `timeout_seconds` denies, same as an explicit "n",
+      # never leaves a payment pending on an agent that's still waiting.
+      # Checkout staleness while the operator was thinking isn't handled
+      # here: the confirmed amount is re-validated by nothing in this class,
+      # but the adapter call `call_adapter` makes right after this passes
+      # hits the real backend, which is the thing that'd reject a checkout
+      # that expired mid-wait — no separate re-check needed.
+      class Terminal
+        DEFAULT_TIMEOUT_SECONDS = 120
+
+        def initialize(timeout_seconds: DEFAULT_TIMEOUT_SECONDS, input: $stdin, output: $stdout)
+          @timeout_seconds = timeout_seconds
+          @input = input
+          @output = output
+        end
+
+        # @raise [Portage::Ucp::ConfirmationDeniedError] on "n", timeout, or
+        #   EOF (stdin closed out from under a headless run) — anything that
+        #   isn't an explicit "y" denies.
+        # @return [Hash] `{approved: true}` on "y".
+        def confirm!(amount:, currency:, merchant:, idempotency_key:)
+          @output.print("Approve payment of #{amount} #{currency} to #{merchant.inspect}? [y/N] ")
+          @output.flush
+
+          answer = read_with_timeout
+          return { approved: true } if answer&.strip&.downcase == "y"
+
+          deny!(answer.nil? ? :timeout : :denied, idempotency_key)
+        end
+
+        private
+
+        def read_with_timeout
+          Timeout.timeout(@timeout_seconds) { @input.gets }
+        rescue Timeout::Error
+          nil
+        end
+
+        def deny!(reason, idempotency_key)
+          message = reason == :timeout ? "confirmation timed out after #{@timeout_seconds}s" : "confirmation denied"
+          raise Portage::Ucp::ConfirmationDeniedError.new(
+            message, reason: reason, decision: { approved: false, reason: reason, idempotency_key: idempotency_key }
+          )
+        end
+      end
+
+      # Always approves. For adapter conformance suites and Dispatcher specs
+      # that need a real `confirm!` call to return without blocking on
+      # stdin — never wire this into a real Dispatcher: confirmation
+      # defaulting to *on* is the thing that makes Phase 1's permanently-
+      # spendable stored token safe (see plan, "No arm step").
+      class AutoApprove
+        def confirm!(**)
+          { approved: true }
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/dispatcher.rb

@@ -4,12 +4,59 @@ module Portage
     # through the CapabilityRegistry to the backing Adapter method, and wraps
     # the result as MCP's dual content/structuredContent output (see §5).
     class Dispatcher
-      def initialize(adapter:, registry: CapabilityRegistry.default)
+      # The one action that moves money — see docs/plans/agentic-payments.md
+      # Phase 0. Gated by name, not capability, since `complete_checkout` is
+      # the only `dev.ucp.shopping.checkout` action that dispatches a charge.
+      PAYMENT_COMPLETING_ACTION = "complete_checkout".freeze
+
+      # @param shop [String, nil] identifies which store this Dispatcher
+      #   instance is completing charges for, threaded straight onto the
+      #   transaction log record — Dispatcher/Adapter have no shared notion
+      #   of shop identity today, so this is nil unless the caller passes one.
+      # @param transaction_log [Support::TransactionLog] reserve/commit
+      #   ledger for `complete_checkout` calls (Phase 0). Injectable so specs
+      #   don't write to the real `~/.portage/transactions.json`.
+      # @param policy [Policy] Phase 2 policy config PolicyGuard.check! reads
+      #   caps/velocity/allowlist/token-scope from. Injectable for the same
+      #   reason as `transaction_log` — defaulting to `Policy.load` would
+      #   have every spec read the real `~/.portage/policy.json`.
+      # @param confirmer [#confirm!] Phase 3 gate, run after PolicyGuard
+      #   passes, before dispatch. Defaults to `Confirmer::Terminal.new`
+      #   (blocks on stdin) — confirmation is on by default per the plan;
+      #   specs and conformance suites inject `Confirmer::AutoApprove.new`
+      #   instead so a run never blocks waiting on a human.
+      # @param order_ledger [Support::OrderLedger] settled-order snapshot
+      #   store (Phase 1, docs/plans/order-ledger.md). Injectable for the
+      #   same reason as `transaction_log` — defaults to the real
+      #   `~/.portage/orders.json`.
+      def initialize(adapter:, registry: CapabilityRegistry.default, logger: Portage::Ucp.configuration.logger,
+                     shop: nil, transaction_log: Support::TransactionLog.new, policy: Policy.load,
+                     confirmer: Confirmer::Terminal.new, order_ledger: Support::OrderLedger.new)
         @adapter = adapter
         @registry = registry
+        @logger = logger
+        @shop = shop
+        @transaction_log = transaction_log
+        @policy = policy
+        @confirmer = confirmer
+        @order_ledger = order_ledger
       end
 
-      def call(capability:, action:, arguments: {})
+      # @param correlation_id [String, nil] threaded through to the adapter
+      #   (via Support::CheckoutState.with_observability, scoped to this call
+      #   only) so a checkout_state_transition event (§12) it emits during
+      #   this call carries the same id as the tool_called event that
+      #   triggered it. Optional, not correlation_id: required, since
+      #   Dispatcher.call is also the conformance kit's
+      #   (lib/portage/ucp/rspec.rb) and specs' direct entry point, outside
+      #   any MCP request (§23).
+      # @param agent_profile [String, nil] caller-supplied `ucp-agent.profile`
+      #   hint from `_meta` (see Mcp::Server.agent_profile_for). Dispatcher
+      #   has no direct Observability.log call of its own to thread this
+      #   into — accepted here purely so callers that already pass
+      #   correlation_id: have a matching, equally optional slot; existing
+      #   callers that omit it are unaffected.
+      def call(capability:, action:, arguments: {}, correlation_id: nil, agent_profile: nil)
         capability_definition = @registry.find(capability)
         raise UnknownCapabilityError, capability if capability_definition.nil?
 
@@ -20,12 +67,129 @@ module Portage
 
         Portage::Ucp::PaymentTokenGuard.validate!(arguments[:payment_token]) if arguments.key?(:payment_token)
 
-        result = @adapter.public_send(method_name, **arguments)
+        result = if action == PAYMENT_COMPLETING_ACTION
+                   call_and_log_transaction(method_name, arguments, correlation_id)
+                 else
+                   call_adapter(method_name, arguments, correlation_id)
+                 end
         wrap(capability, result)
       end
 
       private
 
+      # Reserve-then-commit around the one action that dispatches a charge:
+      # the `pending` record lands *before* `call_adapter` runs, so a crash
+      # during the adapter's own gateway round-trip leaves that record
+      # behind rather than nothing. `amount`/`currency` are unknown at
+      # reserve time (see TransactionLog#reserve) and filled in from the
+      # settled Checkout on success; a raised error settles the record
+      # `failed` before re-raising, never left dangling `pending`.
+      #
+      # PolicyGuard.check! (Phase 2), then the Confirmer (Phase 3), run
+      # after reserve, before dispatch — both need `amount`/`currency` to
+      # check the spend cap / show the operator a prompt, which means
+      # fetching the checkout via `@adapter.get_checkout` up front rather
+      # than waiting for the settled result `call_adapter` would otherwise
+      # provide after the charge already happened. A block or a deny never
+      # reaches `call_adapter` at all; a pass is recorded immediately so it
+      # survives a crash during the adapter round-trip, same reasoning as
+      # `reserve`.
+      def call_and_log_transaction(method_name, arguments, correlation_id)
+        idempotency_key = arguments.fetch(:idempotency_key)
+        token_ref = payment_token_ref(arguments[:payment_token])
+
+        result = settle(method_name, arguments, correlation_id, idempotency_key, token_ref)
+
+        # Snapshot AFTER `complete` inside `settle` above, never before/
+        # interleaved — opposite of `reserve`'s pre-dispatch posture.
+        # Deliberately OUTSIDE `settle`'s rescue: the money has already
+        # moved by this point, so if this write raises it must surface only
+        # after the transaction record is durably `complete` — a lost local
+        # history write must never flip a settled charge to `failed` or
+        # leave the transaction record ambiguous. Not every completed
+        # checkout produces an order (e.g. cart-only flows), so skip
+        # silently when absent.
+        @order_ledger.record(idempotency_key: idempotency_key, order: result.order) if result.order
+        result
+      end
+
+      def settle(method_name, arguments, correlation_id, idempotency_key, token_ref)
+        @transaction_log.reserve(idempotency_key: idempotency_key, shop: @shop,
+                                 checkout_id: arguments[:checkout_id], payment_token_ref: token_ref)
+
+        checkout = @adapter.get_checkout(checkout_id: arguments[:checkout_id])
+        gate!(idempotency_key, checkout, token_ref)
+
+        result = call_adapter(method_name, arguments, correlation_id)
+
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "complete",
+                                  amount: settled_amount(result), currency: settled_currency(result))
+        result
+      rescue StandardError
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "failed")
+        raise
+      end
+
+      # PolicyGuard (Phase 2) then Confirmer (Phase 3), in that order — both
+      # gate the same dispatch, and each phase records its own outcome on
+      # the transaction record as soon as it passes, per `reserve`'s
+      # crash-survives-as-evidence reasoning above.
+      def gate!(idempotency_key, checkout, token_ref)
+        decision = policy_check!(idempotency_key, checkout, token_ref)
+        @transaction_log.record_decision(idempotency_key: idempotency_key, policy_decision: decision)
+
+        confirmation = confirmation_check!(idempotency_key, checkout)
+        @transaction_log.record_confirmation(idempotency_key: idempotency_key, confirmation_outcome: confirmation)
+      end
+
+      def policy_check!(idempotency_key, checkout, token_ref)
+        Portage::Ucp::PolicyGuard.check!(amount: settled_amount(checkout), currency: settled_currency(checkout),
+                                         merchant: @shop, token_ref: token_ref, policy: @policy,
+                                         transaction_log: @transaction_log)
+      rescue Portage::Ucp::PolicyViolationError => e
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "failed", policy_decision: e.decision)
+        raise
+      end
+
+      def confirmation_check!(idempotency_key, checkout)
+        @confirmer.confirm!(amount: settled_amount(checkout), currency: settled_currency(checkout),
+                            merchant: @shop, idempotency_key: idempotency_key)
+      rescue Portage::Ucp::ConfirmationDeniedError => e
+        @transaction_log.complete(idempotency_key: idempotency_key, status: "failed", confirmation_outcome: e.decision)
+        raise
+      end
+
+      # Never persists the payment token itself (single-use, still sensitive
+      # even though PaymentTokenGuard has already ruled out a raw PAN) — only
+      # a one-way reference an operator can correlate against, not replay.
+      def payment_token_ref(payment_token)
+        Support::TokenRef.for(payment_token)
+      end
+
+      def settled_amount(result)
+        return nil unless result.respond_to?(:totals)
+
+        # `Total#amount` is a bare integer minor-unit amount (the parent
+        # object's `currency` applies), not a Money struct — see
+        # value_objects.rb's Total/Item comments.
+        total = Array(result.totals).find { |t| t.type == "total" }
+        total&.amount
+      end
+
+      def settled_currency(result)
+        result.respond_to?(:currency) ? result.currency : nil
+      end
+
+      def call_adapter(method_name, arguments, correlation_id)
+        unless @adapter.is_a?(Portage::Ucp::Support::CheckoutState)
+          return @adapter.public_send(method_name, **arguments)
+        end
+
+        Portage::Ucp::Support::CheckoutState.with_observability(@adapter, @logger, correlation_id) do
+          @adapter.public_send(method_name, **arguments)
+        end
+      end
+
       def wrap(capability_name, result)
         unless result.respond_to?(:to_wire_h)
           return { content: [{ type: "text", text: result.inspect }], structuredContent: result }

data/lib/portage/ucp/errors.rb

@@ -38,5 +38,40 @@ module Portage
     # UCP's freeform "rate_limited" error code, same convention as
     # ConflictError above.
     class UpstreamThrottledError < Error; end
+
+    # Raised by PolicyGuard.check! (docs/plans/agentic-payments.md Phase 2)
+    # when a payment-completing dispatch fails a locally-configured guard —
+    # spend cap, velocity limit, merchant allowlist, or per-token scope.
+    # `reason` is a stable snake_case symbol (not just the message) so a
+    # caller can branch on *why* without parsing prose, matching
+    # OutOfStockError/ConflictError's freeform-error-code convention above.
+    # `decision` carries the same shape PolicyGuard.check! returns on
+    # success, so Dispatcher can persist "blocked, here's why" onto the
+    # Phase 0 transaction record the same way it persists a passing decision.
+    class PolicyViolationError < Error
+      attr_reader :reason, :decision
+
+      def initialize(message, reason:, decision:)
+        super(message)
+        @reason = reason
+        @decision = decision
+      end
+    end
+
+    # Raised by a Confirmer (docs/plans/agentic-payments.md Phase 3) when a
+    # payment-completing dispatch isn't approved — explicit "n", a timeout,
+    # or an async transport's own deny. Same reason/decision shape as
+    # PolicyViolationError above, for the same reasons: a stable symbol to
+    # branch on, and a decision Dispatcher persists onto the Phase 0
+    # transaction record via `confirmation_outcome`.
+    class ConfirmationDeniedError < Error
+      attr_reader :reason, :decision
+
+      def initialize(message, reason:, decision:)
+        super(message)
+        @reason = reason
+        @decision = decision
+      end
+    end
   end
 end