portage-ucp 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11276545531e50962e8e16e8d1c966853adfa8ddb8c1aa3851f7fa89a494b33e
-  data.tar.gz: 7421a957575b40d55200ce54e70335bec9a7c7a735cd0941eb2e1bdec0bdd535
+  metadata.gz: f8228c4a5a32d4ed322103ebc5061bf3179700fae68cc414fd0e53a8cb7f900e
+  data.tar.gz: dfc1f273f7fc79a8af633d4341af409a1447550c56a2fb0e8c7d4301b85c65c4
 SHA512:
-  metadata.gz: 52d85b70ca4e16311c318331bb0ca161c82ff9f833e4d08b5c3e262550ecaeccf334aaf35cf5e39f5a351e3a5aa58ed0a508615003c1da6d54d728a9dc34eda9
-  data.tar.gz: 05e158b1864ae760e08ddb3ab76080a1effd59bfa475ebd64e23f0f2e30f6ff87b4afe44eef0112ca5dda0a6e579e64532df396743cab582373f90e44805b089
+  metadata.gz: 4b7bb63032f231ed97eee56d0ed1d5d85a0fed3fae9c5590a22b153285ce13cc9c362903971bbb9d0a1f9fd0ecb5372e6412f6c38c76ed4f1e17927491006803
+  data.tar.gz: 3046889323d2b87b8ec26523e93bd33ff4edad0345bb858e5f2a75f6c9e0d288e0918cb8b0ee0b3dee467fa47023d7469a254a3e0bfc0ada5aaa527907c1c6fc

data/CHANGELOG.md

@@ -6,6 +6,86 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-15
+
+- **Breaking:** `PaymentEnrollment` results are now validated by the new
+  `PaymentEnrollmentGuard` (design-log §33/Phase B) — every
+  `create_payment_enrollment`/`get_payment_enrollment` response an adapter
+  returns is checked via `Dispatcher#call`: `status` must be `"pending"` or
+  `"complete"`; `"pending"` must carry a `setup_url` and no `payment_token`;
+  `"complete"` must carry a `payment_token` and no `setup_url`. Raises the
+  new `Portage::Ucp::InvalidPaymentEnrollmentError` on a violation. A value
+  that constructed fine before (e.g. `status: "banana"`, or `"complete"`
+  with no token) now raises the first time it crosses `Dispatcher#call` —
+  consumers of `PaymentEnrollment` (`portage-cli`, `portage-ucp-client`)
+  are unaffected since they only branch on the CLI's own wire-level status
+  string, never construct the object themselves.
+- Added `Portage::Ucp::Ap2` — an AP2 mandate shape (design-log §33/Phase B,
+  citing the AP2/UCP payment-handler gap already confirmed at design-log
+  §29/§30). `Ap2::PaymentMandate` (amount, currency, merchant, expires_at,
+  signature) and `Ap2::MandateGuard.validate!` (required fields + expiry —
+  mandate-*shape* validation, not cryptographic AP2 verification; no key
+  infrastructure or trust anchor exists in this repo to verify a signature
+  against). `create_payment_enrollment`/`complete_checkout` take an
+  optional `mandate:` kwarg, shape-checked by `Dispatcher#call` before any
+  adapter sees it; `ReferenceAdapter` accepts one and echoes it back on the
+  enrollment it returns. `PaymentEnrollment` gains an optional `mandate:`
+  field for that echo (safe to add — it's a Portage extension, not a
+  UCP-schema-validated type).
+- Adapter conformance kit (`lib/portage/ucp/rspec.rb`) gains an
+  `app.portage-ucp.payment_enrollment` example proving an adapter's
+  enrollment responses satisfy `PaymentEnrollmentGuard` — previously the
+  kit had zero enrollment coverage; the only existing assertions lived in
+  this gem's own `reference_adapter_conformance_spec.rb`, which ships to
+  nobody.
+- `Support::TransactionLog` and `Support::OrderLedger` are now backed by a
+  pluggable `Store` (design-log §33) — new `Store`/`FileStore` pair on
+  each, mirroring `portage-ucp-journal`. `Dispatcher.new(transaction_log:,
+  order_ledger:)` / `TransactionLog.new(store:)` / `OrderLedger.new(store:)`
+  are the injection points; `path:`/`clock:` still work unchanged as a
+  shorthand for the file-backed default. Pure extract-interface refactor —
+  no behavior change, no new construction-site requirements.
+- Added `app.portage-ucp.payment_method`, `app.portage-ucp.saved_address`, and
+  `app.portage-ucp.shopper_data` — Portage-owned extensions (design-log §22
+  item 7) for saved payment references, saved addresses, and shopper data
+  erasure, shipped together per §16. `oauth_token:` is the authorization
+  boundary on every method, including the two `list_*` reads, since
+  `Mcp::Server` only authorizes/rate-limits calls carrying an
+  `idempotency_key`. `save_payment_method`'s `payment_token:` runs through
+  the existing `PaymentTokenGuard` via `Dispatcher#call`, same as
+  `complete_checkout`. `ReferenceAdapter` implements all three; `Adapter`'s
+  stubs raise `NotImplementedError` until overridden.
+- `Dispatcher.new` gains an optional `journal:` argument (`nil` by default,
+  never `require`d from this gem) — after a successful `complete_checkout`
+  with a settled order, `@journal.record_checkout(shop:, source:, checkout:,
+  idempotency_key:)` runs alongside the existing `order_ledger` write, same
+  after-settle/outside-the-rescue posture. `source` is `"native_ucp"` or
+  `"adapter:<platform>"`, read off the adapter's class. Pairs with the new
+  `portage-ucp-journal` gem's `PurchaseJournal` (design-log §22,
+  docs/plans/storage-abstraction-journal.md) — core takes on no new runtime
+  dependency; a consumer wires the journal in from their own app.
+- Added `Portage::Ucp::Security::Signature` and
+  `Portage::Ucp::Rack::SignatureVerification` — verifies RFC 9421 HTTP
+  Message Signatures on inbound requests per UCP's signature spec
+  (`ucp.dev/2026-04-08/specification/signatures/`), the cryptographic
+  proof-of-consent piece design-log §22 named as the one genuine security
+  hole remaining before 1.0. Verify-before-parse, same posture as
+  `Rack::WebhookEndpoint`; trusted keys reuse `Manifest#signing_keys`'
+  current+next JWK-array shape rather than a second key config.
+- Added `Confirmer::Webhook` (design-log §22 slice, Phase C) — out-of-band
+  approval for the confirmation gate, alongside `Terminal`/`AutoApprove`.
+  POSTs `{amount, currency, merchant, idempotency_key}` to a configured
+  URL, then polls a configured status endpoint (or calls a caller-supplied
+  `wait:` callback, for push-based transports) until approve/deny/timeout.
+  Fails closed on timeout, same as `Terminal`, but with its own longer
+  default timeout (900s vs. `Terminal`'s 120s) — a human already at a
+  terminal isn't the same wait as noticing and acting on a Slack message.
+  Built on `Support::HttpClient`, no new runtime dependency. Non-2xx
+  responses from the confirm/status calls themselves raise the new
+  `Confirmer::WebhookApiError`, distinct from `ConfirmationDeniedError`:
+  one means the out-of-band approver couldn't be reached, the other means
+  it was reached and said no (or never answered).
+
 ## [0.5.0] - 2026-09-14
 
 - Added `Adapter#create_payment_enrollment(idempotency_key:)` /

data/README.md

@@ -23,17 +23,22 @@ in this gem.
 | `Portage::Ucp::Manifest` | Builds the signed `/.well-known/ucp` discovery document. |
 | `Portage::Ucp::Rack::ManifestEndpoint` | Serves that manifest over Rack. |
 | `Portage::Ucp::Rack::WebhookEndpoint` | HMAC-verified inbound order-lifecycle webhooks. |
+| `Portage::Ucp::Security::Signature` / `Portage::Ucp::Rack::SignatureVerification` | Verifies RFC 9421 HTTP Message Signatures on inbound requests per UCP's signature spec — cryptographic proof the call carries a signed AP2/UCP authorization, not just an authenticated caller. Wrap your mounted MCP/UCP endpoint with the Rack middleware; verification runs before the body is parsed. |
 | `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::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; `Confirmer::Webhook` is an out-of-band transport (POST + poll a status URL, or a caller-supplied `wait:` callback) for a Slack/WhatsApp/etc. approval flow — same fail-closed-on-timeout contract, its own longer default timeout. |
 | `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`. |
+| `Portage::Ucp::PaymentEnrollmentGuard` | Validates every `create_payment_enrollment`/`get_payment_enrollment` result an `Adapter` returns — `status` must be `"pending"` (with a `setup_url`, no `payment_token`) or `"complete"` (with a `payment_token`, no `setup_url`). Runs automatically in `Dispatcher#call`. |
+| `Portage::Ucp::Ap2::PaymentMandate` / `Portage::Ucp::Ap2::MandateGuard` | A typed shape for an AP2 payment mandate, and shape-only validation (required fields + expiry — not cryptographic verification) run automatically on any `mandate:` argument passed through `Dispatcher#call`. |
 
 Security defaults are all locked down, not permissive-by-omission —
 `UnconfiguredAuthenticator` rejects every mutating call until you configure a real
 one, `PaymentTokenGuard` rejects raw card numbers before they reach your `Adapter`,
-and manifest signing is opt-in. Full detail in the root README's
+`PaymentEnrollmentGuard`/`Ap2::MandateGuard` reject malformed enrollments/mandates
+before they cross the same boundary, and manifest signing is opt-in. Full detail in
+the root README's
 [Security hooks](https://github.com/tomtom87/Portage#security-hooks--nothing-is-permissive-by-default)
 section.
 
@@ -75,6 +80,18 @@ and the [detailed walkthrough](https://github.com/tomtom87/Portage/blob/main/doc
 for the full agent-side conversation, manifest/webhook Rack mounting, and a real
 adapter to model your own against.
 
+## Swapping the store
+
+`Support::TransactionLog` and `Support::OrderLedger` each accept a `store:`
+(`Dispatcher.new(transaction_log:, order_ledger:)` is the injection point).
+`FileStore` — whole-file `flock` + JSON, `chmod 0600` — is the shipped
+default for both; nothing else ships today. Write your own subclass of
+`Support::TransactionLog::Store` / `Support::OrderLedger::Store` for a real
+database, Redis, or an in-memory double for tests — same posture as
+`portage-ucp-journal`'s `Store`/`FileStore` seam, no bundled second backend
+(see that gem's README). `path:`/`clock:` still work as a shorthand that
+builds a `FileStore` under the hood, so existing callers are unaffected.
+
 ## Checking any store
 
 ```bash

data/lib/portage/ucp/adapter.rb

@@ -71,8 +71,16 @@ module Portage
       # than a generic/platform error, so callers can distinguish a stale-stock
       # failure from e.g. a declined payment.
       # @raise [Portage::Ucp::OutOfStockError] if a line item is no longer available
+      # @param mandate [Portage::Ucp::Ap2::PaymentMandate, nil] an AP2
+      #   mandate authorizing this charge, alongside or instead of relying
+      #   on `payment_token` alone (design-log §33/Phase B). Validated for
+      #   shape (not cryptographically) by Dispatcher#call via
+      #   Ap2::MandateGuard before an adapter ever sees it. Optional and
+      #   `nil` by default — no adapter in this repo has a real PSP to
+      #   verify a mandate's signature against, so this is a pass-through
+      #   slot, same posture as `payment_token` on this same method.
       # @return [Portage::Ucp::Checkout]
-      def complete_checkout(checkout_id:, payment_token:, idempotency_key:) = not_implemented
+      def complete_checkout(checkout_id:, payment_token:, idempotency_key:, mandate: nil) = not_implemented
       # @return [Portage::Ucp::Checkout]
       def cancel_checkout(checkout_id:, idempotency_key:) = not_implemented
 
@@ -135,11 +143,56 @@ module Portage
       # 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.
+      # @param mandate [Portage::Ucp::Ap2::PaymentMandate, nil] an AP2
+      #   mandate presented at enrollment time (design-log §33/Phase B),
+      #   same optional/pass-through posture as `complete_checkout`'s
+      #   `mandate:` above — validated for shape by Dispatcher#call, never
+      #   cryptographically, before an adapter ever sees it.
       # @return [Portage::Ucp::PaymentEnrollment]
-      def create_payment_enrollment(idempotency_key:) = not_implemented
+      def create_payment_enrollment(idempotency_key:, mandate: nil) = not_implemented
       # @return [Portage::Ucp::PaymentEnrollment, nil] nil if the enrollment isn't found
       def get_payment_enrollment(enrollment_id:) = not_implemented
 
+      # --- Payment Method / Saved Address / Shopper Data (app.portage-ucp.*
+      # — Portage extensions, not part of the UCP spec) ---
+      # `oauth_token:` — not `subject:` — is the authorization boundary on
+      # every method below, including the two list_* reads. Mcp::Server
+      # treats a call as mutating only when it takes an idempotency_key
+      # (mcp/server.rb:38), and both the authorize and rate_limit guards
+      # skip non-mutating calls entirely. A bare `subject:` string would let
+      # any caller who knows (or guesses) a subject enumerate another
+      # shopper's saved payment references and addresses — the exact risk
+      # §16 (design-log.md:816-819) calls out lookups against this data for.
+      # Carrying the credential on every call closes that: possession of a
+      # subject grants nothing without a valid oauth_token to derive it from.
+      # Do not "simplify" this back to `subject:`.
+      #
+      # @return [Portage::Ucp::PaymentMethodRef] stores an already-tokenized
+      #   payment_token; PaymentTokenGuard runs on it via Dispatcher#call
+      #   before this method is ever reached (dispatcher.rb:75), so a raw PAN
+      #   never arrives here.
+      def save_payment_method(oauth_token:, payment_token:, idempotency_key:) = not_implemented
+      # @return [Array<Portage::Ucp::PaymentMethodRef>]
+      def list_payment_methods(oauth_token:) = not_implemented
+      # @return [Boolean]
+      def delete_payment_method(oauth_token:, payment_method_id:, idempotency_key:) = not_implemented
+
+      # @return [Portage::Ucp::SavedAddress]
+      def save_address(oauth_token:, address:, idempotency_key:) = not_implemented
+      # @return [Array<Portage::Ucp::SavedAddress>]
+      def list_addresses(oauth_token:) = not_implemented
+      # @return [Boolean]
+      def delete_address(oauth_token:, address_id:, idempotency_key:) = not_implemented
+
+      # Erases every payment method, address, and linked identity Portage
+      # holds for this shopper. Idempotent and safe to repeat: a second call
+      # on an already-erased subject returns zero counts, never raises. A
+      # real adapter must forward the deletion to the PSP/platform's own
+      # API — Portage core never holds the credential behind psp_reference,
+      # only the opaque reference itself.
+      # @return [Portage::Ucp::ShopperDataErasure]
+      def delete_shopper_data(oauth_token:, idempotency_key:) = not_implemented
+
       private
 
       def not_implemented

data/lib/portage/ucp/ap2/mandate.rb

@@ -0,0 +1,21 @@
+module Portage
+  module Ucp
+    module Ap2
+      # A typed shape for an AP2 payment mandate (design-log §33/Phase B,
+      # citing design-log.md:1984-2117's already-confirmed AP2 gap) — the
+      # cart/intent authorization a shopper's agent presents alongside (or
+      # instead of) a bare `payment_token`. `amount`/`currency` mirror the
+      # minor-unit-integer convention `Total#amount` already uses elsewhere
+      # in this gem (see value_objects.rb); `signature` is carried opaquely
+      # — MandateGuard checks the mandate's *shape*, never the signature
+      # itself, since verifying it needs a trust anchor this gem doesn't
+      # have (see MandateGuard's own comment).
+      PaymentMandate = Data.define(:amount, :currency, :merchant, :expires_at, :signature) do
+        def to_wire_h
+          { "amount" => amount, "currency" => currency, "merchant" => merchant,
+            "expires_at" => expires_at, "signature" => signature }
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/ap2/mandate_guard.rb

@@ -0,0 +1,34 @@
+require "time"
+
+module Portage
+  module Ucp
+    module Ap2
+      # Mandate-*shape* validation (design-log §33/Phase B) — required
+      # fields present and not expired. This is deliberately NOT
+      # cryptographic AP2 verification: `signature` is carried opaquely
+      # (see PaymentMandate) and this guard never inspects it. No key
+      # infrastructure or trust anchor exists in this repo to verify a
+      # signature against — that's a real external dependency and an
+      # explicit non-goal here, the same carve-out the existing plan draws
+      # around crypto-signing the confirmation payload. A real PSP adapter
+      # is expected to verify a mandate's signature against the issuing
+      # agent's trust anchor before ever handing it to this gem.
+      module MandateGuard
+        REQUIRED_FIELDS = %i[amount currency merchant expires_at signature].freeze
+
+        def self.validate!(mandate)
+          missing = REQUIRED_FIELDS.reject { |field| mandate.public_send(field) }
+          unless missing.empty?
+            raise Portage::Ucp::InvalidMandateError,
+                  "payment mandate is missing required field(s): #{missing.join(', ')}"
+          end
+
+          return unless Time.now >= Time.parse(mandate.expires_at)
+
+          raise Portage::Ucp::InvalidMandateError,
+                "payment mandate expired at #{mandate.expires_at}"
+        end
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module Portage
       )
 
       ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT, REORDER,
-             PAYMENT_ENROLLMENT].freeze
+             PAYMENT_ENROLLMENT, PAYMENT_METHOD, SAVED_ADDRESS, SHOPPER_DATA].freeze
     end
   end
 end

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

@@ -10,7 +10,7 @@ module Portage
         name: "app.portage-ucp.payment_enrollment",
         version: "1",
         actions: { "create_payment_enrollment" => :create_payment_enrollment,
-                  "get_payment_enrollment" => :get_payment_enrollment }
+                   "get_payment_enrollment" => :get_payment_enrollment }
       )
     end
   end

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

@@ -0,0 +1,28 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extensions, not part of the UCP spec (no ucp.dev
+      # reverse-domain meaning to borrow), same posture as
+      # Capabilities::PAYMENT_ENROLLMENT/REORDER. Advertised only if the
+      # adapter overrides at least one of its own action methods. Kept as
+      # two capabilities (payment methods vs. addresses) rather than one,
+      # per design-log §16/§22 item 7's "ship together, but they're
+      # separate concerns" — a consumer can still gate them independently.
+      PAYMENT_METHOD = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.payment_method",
+        version: "1",
+        actions: { "save_payment_method" => :save_payment_method,
+                   "list_payment_methods" => :list_payment_methods,
+                   "delete_payment_method" => :delete_payment_method }
+      )
+
+      SAVED_ADDRESS = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.saved_address",
+        version: "1",
+        actions: { "save_address" => :save_address,
+                   "list_addresses" => :list_addresses,
+                   "delete_address" => :delete_address }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extension, not part of the UCP spec. Kept separate from
+      # PAYMENT_METHOD/SAVED_ADDRESS: this is the erasure duty over *both*
+      # of those plus the linked identity, not a peer capability alongside
+      # them (design-log §22 item 7).
+      SHOPPER_DATA = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.shopper_data",
+        version: "1",
+        actions: { "delete_shopper_data" => :delete_shopper_data }
+      )
+    end
+  end
+end

data/lib/portage/ucp/confirmer.rb

@@ -1,4 +1,5 @@
 require "timeout"
+require "net/http"
 
 module Portage
   module Ucp
@@ -69,6 +70,107 @@ module Portage
           { approved: true }
         end
       end
+
+      # Raised when the confirm or status HTTP call itself fails (non-2xx,
+      # not the 409 Support::HttpClient already normalizes to ConflictError)
+      # — a transport failure talking to the out-of-band approver, not a
+      # denial by it. Kept distinct from ConfirmationDeniedError: that one
+      # means "someone said no" or "no one answered in time," this one means
+      # "couldn't even ask."
+      class WebhookApiError < Portage::Ucp::Error
+        include Support::ApiError
+
+        private
+
+        def api_label
+          "Confirmer::Webhook"
+        end
+      end
+
+      # Out-of-band approval over plain HTTP: POST the request, then poll a
+      # status endpoint until the out-of-band channel (Slack, WhatsApp,
+      # whatever a caller wires up) records an answer. Core only ever speaks
+      # HTTP here — the actual notification transport is the caller's job,
+      # same "transport-agnostic by design" posture as this module's
+      # top-of-file comment.
+      #
+      # Deliberately its own timeout default, not Terminal::
+      # DEFAULT_TIMEOUT_SECONDS: 120s fits a human already at a keyboard, not
+      # someone who has to notice a Slack message and tap approve.
+      class Webhook
+        include Support::HttpClient
+
+        DEFAULT_TIMEOUT_SECONDS = 900
+        DEFAULT_POLL_INTERVAL_SECONDS = 5
+
+        # @param confirm_url [String] posted `{amount, currency, merchant,
+        #   idempotency_key}` once, to kick off the out-of-band approval.
+        # @param status_url [String] polled (GET, `?idempotency_key=...`)
+        #   for `{"status" => "approved" | "denied" | "pending"}` until it
+        #   stops answering "pending" or `timeout_seconds` elapses.
+        # @param wait [#call, nil] escape hatch for push-based transports —
+        #   when given, called with `idempotency_key` instead of polling,
+        #   and must itself return `"approved"` or `"denied"` (blocking as
+        #   long as it needs to; `timeout_seconds` isn't enforced around it,
+        #   since a push transport is expected to enforce its own).
+        def initialize(confirm_url:, status_url:, timeout_seconds: DEFAULT_TIMEOUT_SECONDS,
+                       poll_interval_seconds: DEFAULT_POLL_INTERVAL_SECONDS, headers: {}, wait: nil)
+          @confirm_url = confirm_url
+          @status_url = status_url
+          @timeout_seconds = timeout_seconds
+          @poll_interval_seconds = poll_interval_seconds
+          @headers = headers
+          @wait = wait
+        end
+
+        # @raise [Portage::Ucp::ConfirmationDeniedError] on an explicit
+        #   deny, or on timeout (fail-closed, same as Terminal).
+        # @raise [Portage::Ucp::Confirmer::WebhookApiError] if the confirm
+        #   or status HTTP call itself fails.
+        # @return [Hash] `{approved: true}` on approval.
+        def confirm!(amount:, currency:, merchant:, idempotency_key:)
+          json_request(Net::HTTP::Post, @confirm_url,
+                       body: { amount: amount, currency: currency, merchant: merchant,
+                               idempotency_key: idempotency_key },
+                       headers: @headers)
+
+          status = @wait ? @wait.call(idempotency_key) : poll(idempotency_key)
+          return { approved: true } if status == "approved"
+
+          deny!(status == "denied" ? :denied : :timeout, idempotency_key)
+        end
+
+        private
+
+        def poll(idempotency_key)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout_seconds
+
+          loop do
+            response = json_request(Net::HTTP::Get, status_url_for(idempotency_key), headers: @headers)
+            return response["status"] if %w[approved denied].include?(response["status"])
+            return "timeout" if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            sleep(@poll_interval_seconds)
+          end
+        end
+
+        def status_url_for(idempotency_key)
+          uri = URI(@status_url)
+          uri.query = "idempotency_key=#{URI.encode_www_form_component(idempotency_key)}"
+          uri
+        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
+
+        def api_error_class
+          WebhookApiError
+        end
+      end
     end
   end
 end

data/lib/portage/ucp/dispatcher.rb

@@ -29,9 +29,15 @@ module Portage
       #   store (Phase 1, docs/plans/order-ledger.md). Injectable for the
       #   same reason as `transaction_log` — defaults to the real
       #   `~/.portage/orders.json`.
+      # @param journal [#record_checkout, nil] optional buyer-side purchase
+      #   journal (docs/plans/storage-abstraction-journal.md) — the
+      #   `portage-ucp-journal` gem's `PurchaseJournal`, or anything
+      #   duck-typed the same way. `nil` by default and never `require`d
+      #   from core (§2: core stays dependency-light); a consumer wires
+      #   one in from their own app after requiring that gem themselves.
       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)
+                     confirmer: Confirmer::Terminal.new, order_ledger: Support::OrderLedger.new, journal: nil)
         @adapter = adapter
         @registry = registry
         @logger = logger
@@ -40,6 +46,7 @@ module Portage
         @policy = policy
         @confirmer = confirmer
         @order_ledger = order_ledger
+        @journal = journal
       end
 
       # @param correlation_id [String, nil] threaded through to the adapter
@@ -65,18 +72,37 @@ module Portage
         method_name = capability_definition.actions[action]
         raise UnknownActionError, action if method_name.nil?
 
-        Portage::Ucp::PaymentTokenGuard.validate!(arguments[:payment_token]) if arguments.key?(:payment_token)
+        validate_inbound_boundaries!(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
+        validate_outbound_boundaries!(result)
         wrap(capability, result)
       end
 
       private
 
+      # PaymentTokenGuard/Ap2::MandateGuard, run before any adapter method
+      # (design-log §9/§33) — whichever action carries the argument, not
+      # gated to complete_checkout, so misuse is caught at the one seam
+      # every call already passes through.
+      def validate_inbound_boundaries!(arguments)
+        Portage::Ucp::PaymentTokenGuard.validate!(arguments[:payment_token]) if arguments.key?(:payment_token)
+        Portage::Ucp::Ap2::MandateGuard.validate!(arguments[:mandate]) if arguments[:mandate]
+      end
+
+      # Outbound counterpart to the above (design-log §33) — every adapter's
+      # create_payment_enrollment/get_payment_enrollment result is held to
+      # PaymentEnrollmentGuard here, not just ReferenceAdapter's own.
+      def validate_outbound_boundaries!(result)
+        return unless result.is_a?(Portage::Ucp::PaymentEnrollment)
+
+        Portage::Ucp::PaymentEnrollmentGuard.validate!(result)
+      end
+
       # 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
@@ -110,6 +136,16 @@ module Portage
         # 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
+
+        # Same after-settle, outside-the-rescue posture as the order_ledger
+        # write immediately above, for the same reason: the money has
+        # already moved, so a lost journal write must never flip a settled
+        # charge to `failed`. @journal is nil unless a consumer opted in
+        # (see #initialize) — never required from core.
+        if @journal && result.order
+          @journal.record_checkout(shop: @shop, source: journal_source(@adapter), checkout: result,
+                                   idempotency_key: idempotency_key)
+        end
         result
       end
 
@@ -180,6 +216,20 @@ module Portage
         result.respond_to?(:currency) ? result.currency : nil
       end
 
+      # "native_ucp" vs "adapter:<platform>" (design-log §22) — Dispatcher
+      # has no separate platform-identity concept of its own, so this reads
+      # it off the adapter's class: the in-repo ReferenceAdapter (and any
+      # anonymous/no-name adapter, e.g. a test double) counts as native_ucp,
+      # every namespaced adapter (Portage::Ucp::Shopify::Adapter, ...)
+      # reports its namespace.
+      def journal_source(adapter)
+        name = adapter.class.name
+        return "native_ucp" if name.nil? || name == "Portage::Ucp::ReferenceAdapter"
+
+        platform = name.split("::")[-2]
+        "adapter:#{(platform || name).downcase}"
+      end
+
       def call_adapter(method_name, arguments, correlation_id)
         unless @adapter.is_a?(Portage::Ucp::Support::CheckoutState)
           return @adapter.public_send(method_name, **arguments)
@@ -190,7 +240,15 @@ module Portage
         end
       end
 
+      # Every existing action returns either a single to_wire_h-capable
+      # object or a bare Array of plain values (never a Data object) — the
+      # new list_payment_methods/list_addresses are the first actions to
+      # return Array<to_wire_h-capable>, which needs its own branch here:
+      # left to the plain `result.inspect` fallback below, a Data-object
+      # array would reach structuredContent unserialized to JSON.
       def wrap(capability_name, result)
+        return wrap_list(result) if result.is_a?(Array) && result.all? { |item| item.respond_to?(:to_wire_h) }
+
         unless result.respond_to?(:to_wire_h)
           return { content: [{ type: "text", text: result.inspect }], structuredContent: result }
         end
@@ -198,6 +256,11 @@ module Portage
         payload = Portage::Ucp::WireEnvelope.wrap(capability_name, result.to_wire_h)
         { content: [{ type: "text", text: payload.inspect }], structuredContent: payload }
       end
+
+      def wrap_list(result)
+        payload = result.map(&:to_wire_h)
+        { content: [{ type: "text", text: payload.inspect }], structuredContent: payload }
+      end
     end
   end
 end

data/lib/portage/ucp/errors.rb

@@ -7,6 +7,19 @@ module Portage
     class CapabilityNotAdvertisedError < Error; end
     class AuthenticationError < Error; end
     class RawPanRejectedError < Error; end
+    # Raised by PaymentEnrollmentGuard.validate! (design-log §33/Phase B)
+    # when an Adapter's create_payment_enrollment/get_payment_enrollment
+    # result doesn't hold the shape `PaymentEnrollment` itself never
+    # enforces — value_objects.rb has no validation of any kind, same
+    # raise-free posture as every other Data.define there, so this is the
+    # guard's own error, not value_objects.rb's.
+    class InvalidPaymentEnrollmentError < Error; end
+    # Raised by Ap2::MandateGuard.validate! (design-log §33/Phase B) — a
+    # mandate that's expired or missing a required field. Mandate-shape
+    # validation only, not cryptographic AP2 verification: no key
+    # infrastructure or trust anchor exists in this repo to verify a
+    # mandate's signature against (see Ap2::MandateGuard's own comment).
+    class InvalidMandateError < Error; end
     class RateLimitExceededError < Error; end
     # Raised by #complete_checkout when the platform rejects completion
     # because a line item is out of stock or otherwise unavailable —

data/lib/portage/ucp/observability.rb

@@ -18,6 +18,7 @@ module Portage
         payment_token oauth_token authorization
         email first_name last_name phone_number
         street_address extended_address address_locality address_region address_country postal_code
+        psp_reference
       ].freeze
       REDACTED = "[REDACTED]".freeze