portage-cli 0.11.0 → 0.13.0

data/lib/portage/cli/buy.rb

@@ -9,6 +9,7 @@ require_relative "payment_methods"
 require_relative "setting"
 require_relative "decisions"
 require_relative "confidence_check"
+require_relative "confidence_state"
 require_relative "checkout_handoff"
 require_relative "money"
 require_relative "notifier"
@@ -122,14 +123,18 @@ module Portage
       #   hand off the real checkout first checks its total against this
       #   (with `quote_currency:`) and reports `quote_changed` instead if it
       #   is higher, in another currency, or missing. See #finish_checkout.
-      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- all keywords; one per flag, plus
+      # @param quote_store [String, nil] the approved quote's store, and
+      # @param quote_title [String, nil] its title — set by `buy --quote`
+      #   alongside quote_total:. Only the confidence check reads them: they
+      #   go into its `approved_quote` (see #confidence_quote).
+      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength, Metrics/AbcSize -- all keywords; one per flag, plus
       # injectable collaborators, each assigned to its own ivar
       def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil,
                      auto_open: nil, notify_webhook: nil, handoff_target: nil, confidence_check: nil,
                      transaction_log: nil, max_price: nil, webmcp_bridge: nil, webmcp_mappings: nil,
                      webmcp_mapping_confirm: nil, autofill: nil, webmcp_autofill_confirm: nil, json: false,
-                     quote_total: nil, quote_currency: nil)
-        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
+                     quote_total: nil, quote_currency: nil, quote_store: nil, quote_title: nil)
+        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength, Metrics/AbcSize
         raw = url.to_s.strip
         @uri = URI.parse(raw =~ %r{\Ahttps?://}i ? raw : "https://#{raw}")
         @query = query
@@ -151,6 +156,8 @@ module Portage
         @json = json
         @quote_total = quote_total
         @quote_currency = quote_currency
+        @quote_store = quote_store
+        @quote_title = quote_title
         @webmcp_bridge = webmcp_bridge
         @decisions = {}
       end
@@ -510,7 +517,9 @@ module Portage
       # call it against. Builds a cart, reads it back through the (already
       # cart/checkout-capable, per the gate in #webmcp_flow) session so
       # #reconcile_checkout has a `get_cart`-shaped document to check against
-      # (there's no checkout document either), then calls the preset's
+      # (there's no checkout document either), stops there if the quote cap,
+      # the mismatch check or the opt-in confidence check holds it
+      # (#webmcp_cart_held_report), and only then calls the preset's
       # `handoff_checkout` tool directly on the bridge — after the cart
       # read-back, not before, so any post-mutation "page not ready" gap
       # (see Transport's own retry) has already been waited out by then.
@@ -536,24 +545,84 @@ module Portage
         end
         return webmcp_handoff_dry_run_report(products, product, preset) if @dry_run
 
-        created = session.create_cart(line_items: [{ product_id: line_item_id_of(product), quantity: @qty }],
-                                      context: buyer_context, meta: agent_meta)
-        cart = session.get_cart(cart_id: created["id"], meta: agent_meta)
-        warnings = reconcile_checkout(product, cart)
+        @product = product
+        cart = webmcp_build_cart(session, product)
+        held = webmcp_cart_held_report(products, product, cart)
+        return held if held
 
         result = @webmcp_bridge.execute_tool(preset.handoff_checkout, {})
         autofill = attempt_webmcp_autofill(preset)
-        webmcp_handoff_report("webmcp", products, cart.merge("continue_url" => url_from_handoff(result)), warnings,
+        webmcp_handoff_report("webmcp", products, cart.merge("continue_url" => url_from_handoff(result)), [],
                               autofill: autofill)
       end
 
+      # The same gates #finish_checkout runs before anything leaves this
+      # process, in the same order, all before the hand-off tool sends the
+      # tab to checkout and before anything is autofilled: the quote cap,
+      # then the deterministic mismatch stop, then (only when a decision
+      # backend is enabled) the confidence check. The confidence check only
+      # sees a cart the first two let through, so it can hold this hand-off
+      # but never let through one they stop.
+      # @return [Hash, nil] the report for the first gate that held, or nil.
+      def webmcp_cart_held_report(products, product, cart)
+        warnings = reconcile_checkout(product, cart)
+        return quote_changed_report("webmcp", products, cart, warnings) if quote_exceeded?(cart)
+        return webmcp_cart_mismatch_report(products, cart, warnings) if warnings.any?
+
+        webmcp_low_confidence_report(products, cart)
+      end
+
+      # A hold here points at the store's cart page, like the mismatch stop:
+      # checkout was never opened, so there's nothing at a checkout URL yet.
+      def webmcp_low_confidence_report(products, cart)
+        verdict = decide_confidence(cart, [])
+        return nil if verdict.nil? || verdict[:proceed]
+
+        handoff_report("webmcp", products, cart.merge("continue_url" => webmcp_cart_page_url), [],
+                       outcome: "low_confidence",
+                       message: "#{low_confidence_message(verdict)} Checkout wasn't opened, and nothing was " \
+                                "autofilled.")
+      end
+
+      # Adds the line to the store's cart, then reads the cart back.
+      def webmcp_build_cart(session, product)
+        created = session.create_cart(line_items: [{ product_id: line_item_id_of(product), quantity: @qty }],
+                                      context: buyer_context, meta: agent_meta)
+        session.get_cart(cart_id: created["id"], meta: agent_meta)
+      end
+
+      # Same fail-closed rule as #full_buy (see #decide_escalation): a cart
+      # that doesn't match the request stops here, before the hand-off tool
+      # sends the tab to checkout and before anything is autofilled. This
+      # flow used to only add the mismatch to `warnings` and carry on to
+      # checkout. The cart already exists on the store, so the report points
+      # at the store's cart page for the person to inspect, not at checkout.
+      # Every preset with a `handoff_checkout` tool today is Shopify's, where
+      # that page is /cart. A cart has no checkout status, so the verdict is
+      # the mismatch alone: `decisions.escalation.reason` is "mismatch", as
+      # on #full_buy's own stop.
+      def webmcp_cart_mismatch_report(products, cart, warnings)
+        @decisions[:escalation] = Decisions.escalation(checkout_status: nil, warnings: warnings)
+        handoff_report("webmcp", products, cart.merge("continue_url" => webmcp_cart_page_url), warnings,
+                       outcome: "checkout_mismatch",
+                       message: "Stopped before checkout — the store's cart didn't match the request: " \
+                                "#{warnings.join(' ')} Nothing was bought, and checkout wasn't opened.")
+      end
+
+      def webmcp_cart_page_url
+        URI.join(@uri, "/cart").to_s
+      end
+
       # Unlike #full_buy's dry run (which still creates a UCP checkout, since
       # that's a document the store drops on its own), a dry run here stops
       # before `create_cart`: every step after it changes something outside
       # this process — a real cart on the store, the bridge's own tab
       # navigated to checkout, and (with autofill on) typing into that page.
       # None of that is safe to do on a preview run, so this only reports
-      # what the run would have done. No checkout_id either, so History
+      # what the run would have done. That also means there's no cart to
+      # reconcile, so unlike #dry_run_report this can never carry
+      # `checkout_mismatch: true`; the real run checks the cart and stops
+      # there instead. No checkout_id either, so History
       # records it as a search, not a purchase.
       def webmcp_handoff_dry_run_report(products, product, preset)
         build_report(
@@ -764,6 +833,7 @@ module Portage
                               message: no_match_message)
         end
 
+        @product = product
         checkout = session.create_checkout(line_items: [{ product_id: line_item_id_of(product), quantity: @qty }],
                                            fulfillment: requested_fulfillment(fulfillment_adapter),
                                            context: buyer_context, meta: agent_meta)
@@ -779,34 +849,78 @@ module Portage
       # (if surprising) checkout response, not a transport error. Buying
       # blind against a mismatch this method could have caught defeats the
       # point of an agent shopping on the buyer's behalf, so this always
-      # checks and surfaces what it finds; PORTAGE_ABORT_ON_CHECKOUT_MISMATCH
-      # additionally refuses to proceed rather than merely warning.
+      # checks, and any warning it returns stops a real purchase before
+      # payment (see #decide_escalation). The quoted total and currency are
+      # #quote_exceeded?'s job, not this method's.
+      #
+      # This is the authoritative check, and it always runs first: the
+      # opt-in model check (#decide_confidence) only ever sees a checkout
+      # that already passed it, and can hold that checkout but never
+      # overrule a warning from here.
       def reconcile_checkout(product, checkout)
         item_id = line_item_id_of(product)
-        line = Array(checkout["line_items"]).find { |li| li.dig("item", "id") == item_id }
+        lines = Array(checkout["line_items"])
+        line = lines.find { |li| li.dig("item", "id") == item_id }
         return ["Store dropped the requested item (#{item_id}) from checkout."] unless line
 
         warnings = []
         if line["quantity"] != @qty
           warnings << "Store checked out quantity #{line['quantity']}, not the requested #{@qty}."
         end
+        warnings + price_mismatches(product, item_id, line, checkout["currency"]) +
+          unrequested_lines(lines.reject { |li| li.equal?(line) })
+      end
+
+      # Only one line is ever requested, so any other line is something the
+      # person never asked for: an upsell, a "shipping protection" add-on,
+      # or (on a WebMCP cart) whatever was already sitting in the store's
+      # cart. One that costs nothing is let through, so a store's free gift
+      # or $0 sample doesn't stop the purchase; one whose cost can't be read
+      # is treated as costing something, so it stops.
+      def unrequested_lines(extras)
+        extras.reject { |li| line_cost(li)&.zero? }.map do |li|
+          label = [li.dig("item", "id"), li.dig("item", "title")].compact.join(" ")
+          "Store added #{label.empty? ? 'a line' : label} to checkout, which wasn't requested."
+        end
+      end
+
+      # The line's own total, else its unit price times its quantity; nil
+      # when the line carries neither.
+      def line_cost(line)
+        total = Portage::Ucp::Support::Totals.amount(line["totals"])
+        return total if total.is_a?(Numeric)
+
+        price = line.dig("item", "price")
+        quantity = line["quantity"] || 1
+        price * quantity if price.is_a?(Numeric) && quantity.is_a?(Numeric)
+      end
+
+      # A unit price is only comparable in the catalog's own currency, so a
+      # checkout in another one is reported as that, not as a price change.
+      def price_mismatches(product, item_id, line, currency)
+        catalog_currency = expected_unit_currency(product, item_id)
+        if catalog_currency && currency && catalog_currency != currency
+          return ["Store checked out in #{currency}, not the catalog's #{catalog_currency}."]
+        end
 
         expected = expected_unit_price(product, item_id)
         actual = line.dig("item", "price")
-        if expected && actual && expected != actual
-          warnings << "Store priced the item at #{actual} #{checkout['currency']} minor units per unit, " \
-                      "not the catalog's #{expected}."
-        end
-        warnings
+        return [] unless expected && actual && expected != actual
+
+        ["Store priced the item at #{actual} #{currency} minor units per unit, not the catalog's #{expected}."]
       end
 
       def expected_unit_price(product, item_id)
-        variant = Array(product["variants"]).find { |v| v["id"] == item_id }
-        variant&.dig("price", "amount") || product.dig("price_range", "min", "amount")
+        expected_price_of(product, item_id)&.dig("amount")
       end
 
-      def abort_on_mismatch?
-        Setting.flag?(env: "PORTAGE_ABORT_ON_CHECKOUT_MISMATCH")
+      def expected_unit_currency(product, item_id)
+        expected_price_of(product, item_id)&.dig("currency")
+      end
+
+      def expected_price_of(product, item_id)
+        variant = Array(product["variants"]).find { |v| v["id"] == item_id }
+        variant&.dig("price") || product.dig("price_range", "min")
       end
 
       # Submits PORTAGE_SHIP_* (see Portage::Cli::ShippingProfile) as the
@@ -963,22 +1077,38 @@ module Portage
         escalation = decide_escalation(checkout, warnings)
         return escalated_report(source, products, checkout, warnings, escalation) if escalation[:escalate]
         return dry_run_report(source, products, checkout, warnings) if @dry_run
-        return webmcp_handoff_report(source, products, checkout, warnings) if force_handoff
+        return webmcp_handoff_checkout_report(source, products, checkout, warnings) if force_handoff
         return confirmation_needed_report(source, products, checkout, warnings) unless confirmed?
 
         complete(session, source, products, checkout, warnings)
       end
 
+      # The non-preset WebMCP hand-off (`express_stop` through #full_buy). Same
+      # last gate as #webmcp_handoff_checkout_flow's: with a decision backend
+      # enabled, the confidence check runs before anything is handed off, on a
+      # checkout the quote cap and the mismatch stop already let through. A
+      # hold reports `low_confidence` pointing at the store's cart page, as the
+      # preset flow's does, so nothing is sent to a `profile` target's checkout.
+      # No backend named: straight to the hand-off, as before.
+      def webmcp_handoff_checkout_report(source, products, checkout, warnings)
+        webmcp_low_confidence_report(products, checkout) ||
+          webmcp_handoff_report(source, products, checkout, warnings)
+      end
+
       # First in #finish_checkout, ahead of the escalation gates: a
       # `quote_changed` refusal never hands off, since that would spend the
       # quote and open a checkout the person never approved. #complete is
       # the only place this file charges, and it is reached only through
       # #finish_checkout.
+      #
+      # A quote with no total (its dry run had none to show, as a WebMCP
+      # preset dry run never does) caps nothing, so it refuses too, rather
+      # than buying at whatever the store now asks.
       def quote_exceeded?(checkout)
-        return false unless @quote_total
+        return false unless quote_run?
 
         total = checkout_total(checkout)
-        total.nil? || total > @quote_total || checkout["currency"] != @quote_currency
+        @quote_total.nil? || total.nil? || total > @quote_total || checkout["currency"] != @quote_currency
       end
 
       def quote_changed_report(source, products, checkout, warnings)
@@ -990,6 +1120,11 @@ module Portage
       end
 
       def quote_changed_message(total, currency)
+        if @quote_total.nil?
+          return "The quote has no total to hold this checkout (now #{quoted_amount(total, currency)}) to — " \
+                 "nothing was bought. Dry-run again for a priced quote."
+        end
+
         "The price changed since the quote (was #{quoted_amount(@quote_total, @quote_currency)}, " \
           "now #{quoted_amount(total, currency)}) — nothing was bought."
       end
@@ -998,15 +1133,18 @@ module Portage
 
       # Hand off vs. keep going is Decisions.escalation's call
       # (docs/plans/system-one-decision-layer.md § Responsibilities 2): a
-      # literal `requires_escalation` status always escalates. A mismatch
-      # from #reconcile_checkout escalates only under
-      # PORTAGE_ABORT_ON_CHECKOUT_MISMATCH. By default the warnings are
-      # surfaced on the report, and the purchase is not stopped for them.
+      # literal `requires_escalation` status always escalates, and so does
+      # any mismatch from #reconcile_checkout, with no setting to turn that
+      # off. This used to only warn unless PORTAGE_ABORT_ON_CHECKOUT_MISMATCH
+      # was set, so by default a checkout that didn't match what the person
+      # approved was still paid for and reported `purchased`. That variable
+      # is now ignored. A --dry-run never pays, so there the mismatch stays
+      # in `warnings` and #dry_run_report flags it instead, since an agent
+      # needs the priced checkout to tell the person what went wrong.
       # The verdict lands on the report's `decisions:`, and the report's
       # `outcome:` names which gate (if any) stopped the purchase.
       def decide_escalation(checkout, warnings)
-        verdict = Decisions.escalation(checkout_status: checkout["status"],
-                                       warnings: abort_on_mismatch? ? warnings : [])
+        verdict = Decisions.escalation(checkout_status: checkout["status"], warnings: @dry_run ? [] : warnings)
         @decisions[:escalation] = verdict
         verdict
       end
@@ -1129,17 +1267,48 @@ module Portage
         Portage::Ucp::Support::Totals.amount(checkout["totals"])
       end
 
-      # Never includes the payment token: the state goes to a model backend,
-      # which may be a hosted API (Jev).
+      # Runs only on a checkout that already passed #reconcile_checkout, the
+      # quote cap and the spend policy, so it can hold a purchase but never
+      # let through one those would stop. The state is ConfidenceState's
+      # allowlisted summary — never the payment token, the address or the
+      # buyer's contact details — because it goes to a model backend that
+      # may be a hosted third-party API (Jev).
       def decide_confidence(checkout, warnings)
-        verdict = confidence_check.call(
-          query: @query, merchant: @uri.host, quantity: @qty, warnings: warnings,
-          checkout: checkout.slice("id", "status", "currency", "line_items", "totals")
-        )
+        return nil unless confidence_check.enabled?
+
+        verdict = confidence_check.call(confidence_state(checkout, warnings))
         @decisions[:confidence] = verdict if verdict
         verdict
       end
 
+      def confidence_state(checkout, warnings)
+        item_id = @product && line_item_id_of(@product)
+        ConfidenceState.build(
+          request: { query: @query, merchant: @uri.host, quantity: @qty, item_id: item_id,
+                     item_title: picked_title(item_id) },
+          checkout: checkout, warnings: warnings, quote: confidence_quote
+        )
+      end
+
+      # The picked product's title from the store's own search, plus its
+      # variant's when the checked-out variant has one ("Tee — Large").
+      def picked_title(item_id)
+        return nil unless @product
+
+        [@product["title"], variant_matching(@product, item_id)&.dig("title")].compact.uniq.join(" — ")
+      end
+
+      # What `buy --quote` pinned, as the person approved it. nil on a run
+      # with no quote.
+      def confidence_quote
+        return nil unless quote_run?
+
+        { store: @quote_store, product_id: @product_id, title: @quote_title, quantity: @qty,
+          total: @quote_total, currency: @quote_currency }
+      end
+
+      def quote_run? = !(@quote_store || @quote_total || @quote_currency).nil?
+
       def confidence_check
         @confidence_check ||= ConfidenceCheck.new
       end
@@ -1410,9 +1579,18 @@ module Portage
         @yes
       end
 
+      # `warnings` here are #reconcile_checkout's mismatches, which a real
+      # run of the same checkout stops on — so the report says so up front,
+      # before anyone approves a quote for it.
       def dry_run_report(source, products, checkout, warnings = [])
-        checkout_report(source, products, checkout, outcome: "dry_run", warnings: warnings,
-                                                    message: "Dry run — checkout created but not completed.")
+        message = "Dry run — checkout created but not completed."
+        extra = {}
+        if warnings.any?
+          message += " It doesn't match the request (#{warnings.join(' ')}), so a real purchase would stop " \
+                     "with checkout_mismatch."
+          extra[:checkout_mismatch] = true
+        end
+        checkout_report(source, products, checkout, outcome: "dry_run", warnings: warnings, message: message, **extra)
       end
 
       def confirmation_needed_report(source, products, checkout, warnings = [])

data/lib/portage/cli/compare.rb

@@ -57,12 +57,13 @@ module Portage
         return report(message: "#{uri.host} is hand-off only — #{HandoffOnly::LEGAL_NOTICE}") \
           if @handoff_only.host?(uri.host)
 
-        session = discover(origin_of(uri))
-        return report(message: "#{origin_of(uri)} doesn't speak UCP.") unless session
+        origin = OfferSources.origin_of(uri.to_s)
+        session = discover(origin)
+        return report(message: "#{origin} doesn't speak UCP.") unless session
 
         wrapped = session.get_product(product_id: @origin_product_id)
         product = wrapped.is_a?(Hash) ? wrapped["product"] : nil
-        return report(message: "Product #{@origin_product_id.inspect} not found at #{origin_of(uri)}.") unless product
+        return report(message: "Product #{@origin_product_id.inspect} not found at #{origin}.") unless product
 
         { host: uri.host, title: field(product, "title"), product: product }
       end

data/lib/portage/cli/confidence_check.rb

@@ -8,7 +8,9 @@ module Portage
     # § Responsibilities 3) as `portage buy` uses it: one yes/no question put
     # to a Decision::ModelBackends backend right before an unattended
     # (`--yes`) completion — "is this checkout what the shopper asked for,
-    # and safe to complete without a person looking at it?"
+    # and safe to complete without a person looking at it?" Also asked
+    # before the WebMCP preset flow sends the browser to the store's
+    # checkout and autofills it (Buy#webmcp_cart_held_report).
     #
     # Default off. Nothing asks a model anything unless a backend is named,
     # via `--decision-backend NAME` or PORTAGE_DECISION_BACKEND (`jev` or
@@ -22,6 +24,16 @@ module Portage
     # purchase and hands the checkout to the shopper. It never
     # auto-approves anything `--yes` wouldn't already have allowed.
     #
+    # Additive only. Buy runs it after #reconcile_checkout's deterministic
+    # mismatch check, the quote cap and the spend policy, and only on a
+    # checkout all three let through, so a "yes" here can never let
+    # through a purchase one of those would stop. A "no" can only hold it.
+    #
+    # What it sends is ConfidenceState's allowlisted summary, never the
+    # raw checkout: no payment token, no address, no buyer contact
+    # details. #call JSON-encodes whatever state it is given, so a caller
+    # outside Buy has to build its state the same way.
+    #
     # Fails closed. An unknown backend name, a backend that isn't configured
     # (no JEV_API_KEY, no Laya bridge), or a backend call that fails all hold
     # the purchase, the same as a low score does. So does naming a backend
@@ -35,11 +47,18 @@ module Portage
       QUESTION = "safe_to_complete".freeze
       # Phrased so "yes" means "proceed": a noul answer's value is the
       # probability of yes, and that is what ConfidenceGate thresholds.
-      INSTRUCTIONS = "The state is a checkout an agent built on a shopper's behalf: the shopper's search " \
-                     "query, the merchant, the requested quantity, the checkout's line items and totals, and " \
-                     "any warnings about where the checkout differs from the request. Answer yes only if the " \
-                     "checkout clearly matches what the shopper asked for and is safe to complete without a " \
-                     "person reviewing it first.".freeze
+      INSTRUCTIONS = "The state is a summary of a checkout an agent built on a shopper's behalf. `request` " \
+                     "is what the shopper asked for: the search query, the store, the quantity, and the item " \
+                     "picked from the store's search results. `approved_quote`, when present, is the exact " \
+                     "purchase the shopper approved beforehand: store, product, title, quantity, total and " \
+                     "currency. `checkout` is what the store is about to charge for: its line items (`requested` " \
+                     "marks the line that was asked for), totals including any shipping, tax and fees, " \
+                     "discounts and the selected shipping option. `warnings` lists differences an automatic " \
+                     "check already found. Answer yes only if the checkout clearly matches the request and, " \
+                     "when there is one, the approved quote: the same product (not a different model, size, " \
+                     "bundle or subscription), the same quantity, no extra items, and a total with no " \
+                     "surprising shipping, fees or other charges. Answer no if anything is unclear, missing " \
+                     "or doesn't fit, or if the checkout would need a person to review it before paying.".freeze
 
       # @param backend [String, nil] a ModelBackends::REGISTRY key; nil
       #   defers to PORTAGE_DECISION_BACKEND.
@@ -64,7 +83,8 @@ module Portage
 
       def enabled? = !@backend_name.nil?
 
-      # @param state [Hash] JSON-serializable. Never pass it a payment token.
+      # @param state [Hash] JSON-serializable — ConfidenceState.build's
+      #   output. Never a payment token, address or contact detail.
       # @return [Hash, nil] nil when disabled. Otherwise `proceed:`,
       #   `reason:`, `confidence:`, `threshold:`, `backend:` and `error:`.
       #   `reason` is nil when it proceeds, else why it held:

data/lib/portage/cli/confidence_state.rb

@@ -0,0 +1,109 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    # The state ConfidenceCheck sends to its model backend, which may be a
+    # hosted third-party API (Jev, run by TypeSafe). Built from an allowlist:
+    # every field below is copied by name, and nothing else in the checkout
+    # hash is ever read. A store can put a buyer block, a shipping address,
+    # payment handlers or anything else on its checkout, and none of it
+    # reaches the backend, because this never copies a sub-hash wholesale.
+    #
+    # Never sent: the payment token (or any token reference), the shipping
+    # address and destinations, the buyer's name, phone or email, links and
+    # continue URLs, ids of the checkout itself, image URLs, discount codes,
+    # and anything read from the environment.
+    #
+    # Sent:
+    # - `request`: the search query, the store's host, the requested
+    #   quantity, and the item id and title that were picked from the
+    #   store's own search results.
+    # - `approved_quote` (only on `buy --quote`): the store, product id,
+    #   title, quantity, total and currency the person approved.
+    # - `checkout`: its status and currency; each line's item id, title,
+    #   unit price, quantity, line totals and whether it is the requested
+    #   line; the checkout's totals (subtotal, shipping, tax, fees, total:
+    #   whatever types the store sends); applied discounts' titles and
+    #   amounts; and the title and price of each selected shipping option.
+    # - `warnings`: the deterministic check's warnings, if any.
+    #
+    # Strings are cut to MAX_STRING characters and anything that isn't a
+    # string, number, boolean or nil is dropped, so a store can't smuggle a
+    # nested object (or a very long prompt) in through a title.
+    module ConfidenceState
+      MAX_STRING = 200
+
+      module_function
+
+      # @param request [Hash] `query:`, `merchant:`, `quantity:`,
+      #   `item_id:`, `item_title:`.
+      # @param checkout [Hash] a checkout or cart wire hash, string-keyed.
+      # @param warnings [Array<String>]
+      # @param quote [Hash, nil] `store:`, `product_id:`, `title:`,
+      #   `quantity:`, `total:`, `currency:` — nil when the run has no
+      #   approved quote.
+      # @return [Hash] JSON-serializable, string-keyed.
+      def build(request:, checkout:, warnings:, quote: nil)
+        state = { "request" => pick(request, %i[query merchant quantity item_id item_title]) }
+        state["approved_quote"] = pick(quote, %i[store product_id title quantity total currency]) if quote
+        state["checkout"] = checkout_summary(checkout, request[:item_id])
+        state["warnings"] = Array(warnings).map { |warning| scalar(warning.to_s) }
+        state
+      end
+
+      def checkout_summary(checkout, requested_id)
+        { "status" => scalar(checkout["status"]), "currency" => scalar(checkout["currency"]),
+          "line_items" => Array(checkout["line_items"]).map { |line| line_summary(line, requested_id) },
+          "totals" => totals_summary(checkout["totals"]),
+          "discounts" => discounts_summary(checkout["discounts"]),
+          "shipping" => shipping_summary(checkout["fulfillment"]) }
+      end
+
+      def line_summary(line, requested_id)
+        line = {} unless line.is_a?(Hash)
+        item = line["item"].is_a?(Hash) ? line["item"] : {}
+        { "item_id" => scalar(item["id"]), "title" => scalar(item["title"]), "unit_price" => scalar(item["price"]),
+          "quantity" => scalar(line["quantity"]), "totals" => totals_summary(line["totals"]),
+          "requested" => !requested_id.nil? && item["id"] == requested_id }
+      end
+
+      def totals_summary(totals)
+        hashes(totals).map { |total| { "type" => scalar(total["type"]), "amount" => scalar(total["amount"]) } }
+      end
+
+      def discounts_summary(discounts)
+        applied = discounts.is_a?(Hash) ? discounts["applied"] : nil
+        hashes(applied).map do |discount|
+          { "title" => scalar(discount["title"]), "amount" => scalar(discount["amount"]) }
+        end
+      end
+
+      # Only the options the checkout has selected — the price the person
+      # pays for shipping — never the destinations they're priced for.
+      def shipping_summary(fulfillment)
+        methods = fulfillment.is_a?(Hash) ? fulfillment["methods"] : nil
+        hashes(methods).flat_map { |method| hashes(method["groups"]) }.filter_map do |group|
+          option = hashes(group["options"]).find { |o| o["id"] == group["selected_option_id"] }
+          next unless option
+
+          { "title" => scalar(option["title"]),
+            "amount" => scalar(Portage::Ucp::Support::Totals.amount(hashes(option["totals"]))) }
+        end
+      end
+
+      def pick(hash, keys)
+        keys.to_h { |key| [key.to_s, scalar(hash[key])] }
+      end
+
+      def hashes(value) = Array(value).grep(Hash)
+
+      def scalar(value)
+        case value
+        when String then value[0, MAX_STRING]
+        when Integer, true, false, nil then value
+        when Float then value.finite? ? value : nil
+        end
+      end
+    end
+  end
+end