portage-ucp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: add1fc4dcd1b12c3dea3ade248972c2fd2616233b074230838daccce41c9033d
-  data.tar.gz: e75364c190c83ee0b9f6bc43f2aca2ef5067d8a4baf3ad5c1b6534fd1096abd7
+  metadata.gz: 8ce343c7abccfbe4c1a8cf2ed0db6340d588c770e959fef42aec644ef6a69800
+  data.tar.gz: 7d1a96bb2e150b822c1dedbe95b8b3f14fbced7d6be9b5287e120e3e8152059f
 SHA512:
-  metadata.gz: 72c18740172d1aeec163bbc7754d2190f59a92c8fa347256e344ff247ff30b8d4a046ad7f368c7b458b24be9e012748e045f7b4d059b9cef6df509c2aab200da
-  data.tar.gz: 2fd42daa906727619d78a276926461c886ec9b20ce81e9bc5c99fe5b0e229172696edef94df5e9ef108ebc6cedcfb1435b62c6590ae96e2ccaaeb218b8778713
+  metadata.gz: 0cd44b69ef19d804c91696b6477e3616eb9dd64c326754f5ff7f142ff494bdaf42b1bd4686888dcb1d7c6e6198b737cc501384278a9a6d2441173b6191029eab
+  data.tar.gz: 22a096bb7ab8cfaa6285ad12b8c5dfd8098c40f4f538115688e03ad5eac59273f16eca247d1409e28f8f30c730d9ef7cb7c7a5d19586bdacb0c0f002f0b61e9a

data/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.
 
+## [0.3.0] - 2026-08-27
+
+- `Portage::Ucp::Support::Retry` (`lib/portage/ucp/support/retry.rb`) —
+  bounded retry with backoff for adapters, plus normalized conflict/throttle
+  errors on `Support::ApiError` so a caller can distinguish "retry this" from
+  "don't."
+- `Portage::Ucp::Support::SessionLock` (`lib/portage/ucp/support/session_lock.rb`)
+  — serializes per-cart/checkout mutations against a single upstream session,
+  used by the Shopify and Wix adapters to stop concurrent cart writes from
+  racing the same checkout.
+- `Support::Idempotency` is now thread-safe under concurrent duplicate calls
+  — the dedup table write was not atomic, so two requests with the same
+  idempotency key arriving together could both miss the cache and both hit
+  the adapter.
+- Conformance kit: the repeated-idempotency-key example no longer passes on
+  output equality alone. An adapter wired to a fixed-response test double
+  returns identical output whether or not it deduped, so the example now also
+  asserts the key reached `Support::Idempotency`'s dedup table when the
+  adapter includes that module, and `warn`s (rather than silently passing)
+  when it doesn't.
+
+- `Portage::Ucp::ReferenceAdapter` (`lib/portage/ucp/reference_adapter.rb`) —
+  the in-memory `Adapter` roadmap §8 step 1 called for and design-log §17
+  flagged as missing outside `spec/support/fake_adapter.rb`, ships with the
+  gem now. Implements every capability including
+  `discount_codes_supported?`/`fulfillment_supported?`/`link_identity` — the
+  first adapter in this repo to back identity linking at all.
+- `Portage::Ucp::RSpec`/`portage/ucp/rspec.rb` — the adapter conformance kit
+  design-log §17 called "the missing piece that turns 'any backend that
+  implements Adapter' from a README claim into something checked": an
+  `it_behaves_like "a portage adapter"` shared-examples suite checking the
+  contract's behavioral guarantees (idempotency dedup, the PAN guard,
+  schema-conformant wire output, `OutOfStockError` on a stale-stock line) —
+  not loaded by `require "portage/ucp"`, opt-in via `require
+  "portage/ucp/rspec"` since it pulls in RSpec itself. Exercised against
+  `ReferenceAdapter` in this gem's own suite
+  (`spec/reference_adapter_conformance_spec.rb`); wired into each adapter
+  gem's own spec suite (`spec/portage/ucp/<platform>/conformance_spec.rb`)
+  as follow-up.
+- Conformance kit: `existing_variant_id` alongside `existing_product_id`, for
+  adapters (Shopify) where a catalog lookup id and a cart line-item id are
+  different GIDs. Defaults to `existing_product_id`, so every other adapter
+  is unaffected.
+- `search_catalog`/`get_product` output is schema-wrapped like every other
+  capability now — previously returned a bare array/`Product` with no
+  `to_wire_h`, so the dispatcher's schema-wrap never touched it and nothing
+  caught it drifting from `catalog_search.json`/`catalog_lookup.json`.
+
 ## [0.2.0] - 2026-08-21
 
 - `Portage::Ucp::OutOfStockError` — the contract for `#complete_checkout`

data/lib/portage/ucp/adapter.rb

@@ -4,9 +4,11 @@ module Portage
     #   Unoverridden methods leave that capability out of the manifest.
     class Adapter
       # --- Catalog (dev.ucp.shopping.catalog) ---
-      # @return [Array<Portage::Ucp::Product>]
+      # @return [Portage::Ucp::CatalogSearchResult]
       def search_catalog(query:, limit:) = not_implemented
-      # @return [Portage::Ucp::Product, nil]
+      # nil when the product isn't found, same not-found posture as
+      # get_cart/get_checkout/get_order.
+      # @return [Portage::Ucp::ProductDetail, nil]
       def get_product(product_id:) = not_implemented
 
       # --- Cart (dev.ucp.shopping.cart) ---

data/lib/portage/ucp/errors.rb

@@ -16,5 +16,27 @@ module Portage
     # standardized "out_of_stock"/"item_unavailable" error codes
     # (schemas/shopping/types/error_code.json).
     class OutOfStockError < Error; end
+    # Raised when a mutation collides with a concurrent write upstream (HTTP
+    # 409, or a platform's own optimistic-concurrency rejection) — the
+    # resource changed between this call's read and its write. Support::Retry
+    # deliberately never retries this itself: the state it read is already
+    # stale, so retrying blindly would just collide again. The caller is
+    # expected to re-read (get_cart/get_checkout) and resubmit against
+    # current state. Maps to UCP's freeform "conflict" error code —
+    # error_code.json's examples list isn't exhaustive ("freeform codes are
+    # permitted"); "conflict" follows the same snake_case convention as its
+    # "out_of_stock"/"payment_failed" examples, same justification
+    # OutOfStockError above relies on.
+    class ConflictError < Error; end
+    # Raised when Support::Retry exhausts its bounded backoff against a
+    # genuinely-retryable upstream throttle (Shopify GraphQL THROTTLED, HTTP
+    # 429, or cartSubmitForCompletion's SubmitThrottled pollAfter) and the
+    # platform still hasn't done the work. Named apart from
+    # RateLimitExceededError — that one is this gem's own pluggable
+    # RateLimiter rejecting a call before it ever reaches the network; this
+    # is the upstream platform itself refusing after every retry. Maps to
+    # UCP's freeform "rate_limited" error code, same convention as
+    # ConflictError above.
+    class UpstreamThrottledError < Error; end
   end
 end

data/lib/portage/ucp/reference_adapter.rb

@@ -0,0 +1,282 @@
+require "digest"
+
+module Portage
+  module Ucp
+    # In-memory Adapter implementing every capability in the contract,
+    # including dev.ucp.shopping.discount/fulfillment/identity — roadmap §8
+    # step 1 called for one of these ("no real backend required to prove the
+    # protocol layer works") and it never shipped; `spec/support/fake_adapter.rb`
+    # filled that gap for the core gem's own specs, but stayed test-only,
+    # catalog/cart/checkout/order only, and undocumented outside this repo.
+    #
+    # Two jobs: a copy-paste starting point for a third-party adapter author
+    # (see README "Writing your own adapter"), and the fixture the
+    # conformance kit (Portage::Ucp::RSpec, lib/portage/ucp/rspec.rb) runs its
+    # own shared examples against to prove the kit itself is correct.
+    #
+    # Not a mock — every mutating action does the real bookkeeping (line-item
+    # totals, checkout status transitions, order adjustments) an adapter over
+    # a live platform would, just against an in-process Hash instead of an
+    # HTTP API. `seed_product` is the one method with no `Adapter` contract
+    # counterpart — there is no real backend to seed real data into.
+    class ReferenceAdapter < Portage::Ucp::Adapter
+      include Portage::Ucp::Support::Idempotency
+      include Portage::Ucp::Support::CheckoutState
+
+      # Products whose id starts with this prefix are treated as sold out —
+      # #complete_checkout raises Portage::Ucp::OutOfStockError for them, the
+      # same way a real adapter's stock re-check (Adapter#complete_checkout's
+      # docs, design-log §16) would. Lets the conformance kit exercise that
+      # path without depending on adapter-specific seed data.
+      OUT_OF_STOCK_PREFIX = "oos_".freeze
+
+      def initialize
+        super
+        @products = {}
+        @carts = {}
+        @checkouts = {}
+        @orders = {}
+        @identities = {}
+        @next_id = 0
+      end
+
+      # Not part of the Adapter contract — this adapter has no backend to
+      # seed real data into, so callers (a spec, a README example) hand it
+      # catalog fixtures directly.
+      def seed_product(product)
+        @products[product.id] = product
+      end
+
+      def search_catalog(query:, limit:)
+        matches = @products.values.select { |p| p.title.downcase.include?(query.downcase) }.first(limit)
+        Portage::Ucp::CatalogSearchResult.new(products: matches)
+      end
+
+      def get_product(product_id:)
+        product = @products[product_id]
+        product && Portage::Ucp::ProductDetail.new(product: product)
+      end
+
+      def get_cart(cart_id:) = @carts[cart_id]
+
+      def create_cart(line_items:, idempotency_key:, discount_codes: nil)
+        dedup(idempotency_key) do
+          id = next_id("cart")
+          @carts[id] = build_cart(id, line_items, discount_codes)
+        end
+      end
+
+      def update_cart(cart_id:, line_items:, idempotency_key:, discount_codes: nil)
+        dedup(idempotency_key) do
+          @carts[cart_id] = build_cart(cart_id, line_items, discount_codes, previous: @carts[cart_id])
+        end
+      end
+
+      def cancel_cart(cart_id:, idempotency_key:)
+        dedup(idempotency_key) do
+          @carts.delete(cart_id)
+          Portage::Ucp::Cart.new(id: cart_id, line_items: [], currency: "USD", totals: zero_totals)
+        end
+      end
+
+      def create_checkout(line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil)
+        dedup(idempotency_key) do
+          id = next_id("chk")
+          record_checkout_status(id, "incomplete")
+          @checkouts[id] = build_checkout(id, line_items, discount_codes, fulfillment, status: "incomplete")
+        end
+      end
+
+      def get_checkout(checkout_id:) = @checkouts[checkout_id]
+
+      def update_checkout(checkout_id:, line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil)
+        dedup(idempotency_key) do
+          record_checkout_status(checkout_id, "incomplete")
+          @checkouts[checkout_id] = build_checkout(checkout_id, line_items, discount_codes, fulfillment,
+                                                   status: "incomplete", previous: @checkouts[checkout_id])
+        end
+      end
+
+      # payment_token: is part of the Adapter contract's call signature (and
+      # already validated as non-PAN by PaymentTokenGuard before this ever
+      # runs, per §9) but this in-memory adapter has no payment processor to
+      # pass it on to — nothing here should hold onto it any longer than the
+      # single call needs to, so it's accepted and left unused rather than
+      # stored (see .rubocop.yml's Lint/UnusedMethodArgument exclude, same
+      # posture as the abstract Adapter#complete_checkout it overrides).
+      def complete_checkout(checkout_id:, payment_token:, idempotency_key:)
+        dedup(idempotency_key) do
+          checkout = @checkouts.fetch(checkout_id)
+          raise_if_any_line_out_of_stock!(checkout)
+
+          order = store_order(checkout)
+          confirmation = Portage::Ucp::OrderConfirmation.new(id: order.id, permalink_url: order.permalink_url)
+          record_checkout_status(checkout_id, "completed")
+          @checkouts[checkout_id] = Portage::Ucp::Checkout.new(**checkout.to_h, status: "completed",
+                                                                                order: confirmation)
+        end
+      end
+
+      def cancel_checkout(checkout_id:, idempotency_key:)
+        dedup(idempotency_key) do
+          record_checkout_status(checkout_id, "canceled")
+          checkout = @checkouts.fetch(checkout_id)
+          @checkouts[checkout_id] = Portage::Ucp::Checkout.new(**checkout.to_h, status: "canceled")
+        end
+      end
+
+      def get_order(order_id:) = @orders[order_id]
+
+      def cancel_order(order_id:, idempotency_key:, reason: nil)
+        dedup(idempotency_key) do
+          add_adjustment(order_id, type: "cancellation", status: "completed", description: reason)
+        end
+      end
+
+      def request_return(order_id:, line_items:, idempotency_key:, reason: nil)
+        dedup(idempotency_key) do
+          add_adjustment(order_id, type: "return", status: "pending", line_items: line_items, description: reason)
+        end
+      end
+
+      def refund_order(order_id:, line_items:, idempotency_key:, reason: nil)
+        dedup(idempotency_key) do
+          add_adjustment(order_id, type: "refund", status: "completed", line_items: line_items, description: reason)
+        end
+      end
+
+      def discount_codes_supported? = true
+      def fulfillment_supported? = true
+
+      # Accepts any non-blank token and mints a stable identity for it — real
+      # OAuth verification is a platform concern this in-memory adapter has
+      # no platform to defer to, same posture as PaymentTokenGuard drawing
+      # the line at "rejects the clearest misuse" rather than proving
+      # validity.
+      def link_identity(oauth_token:)
+        raise Portage::Ucp::AuthenticationError, "blank oauth_token" if oauth_token.to_s.empty?
+
+        @identities[oauth_token] ||= Portage::Ucp::Identity.new(
+          subject: "user_#{Digest::SHA256.hexdigest(oauth_token)[0, 12]}",
+          email: nil, linked_at: Time.now.utc.iso8601
+        )
+      end
+
+      private
+
+      def add_adjustment(order_id, type:, status:, line_items: [], description: nil)
+        order = @orders.fetch(order_id)
+        adjustment = Portage::Ucp::Adjustment.new(
+          id: next_id("adj"), type: type, occurred_at: Time.now.utc.iso8601, status: status,
+          line_items: adjustment_line_items(line_items), totals: adjustment_totals(order, line_items),
+          description: description
+        )
+        @orders[order_id] = Portage::Ucp::Order.new(**order.to_h, adjustments: order.adjustments + [adjustment])
+      end
+
+      def adjustment_line_items(line_items)
+        return nil if line_items.empty?
+
+        line_items.map { |li| { "id" => li[:id], "quantity" => -li[:quantity] } }
+      end
+
+      def adjustment_totals(order, line_items)
+        return nil if line_items.empty?
+
+        amount = line_items.sum do |li|
+          order_line = order.line_items.find { |oli| oli.id == li[:id] }
+          unit_price = order_line.totals.find { |t| t.type == "total" }.amount / order_line.quantity
+          unit_price * li[:quantity]
+        end
+        [Portage::Ucp::Total.new(type: "total", amount: -amount)]
+      end
+
+      def store_order(checkout)
+        id = next_id("ord")
+        order = Portage::Ucp::Order.new(
+          id: id, checkout_id: checkout.id, permalink_url: "https://example.com/orders/#{id}",
+          line_items: checkout.line_items, fulfillment: Portage::Ucp::Fulfillment.new,
+          currency: checkout.currency, totals: checkout.totals
+        )
+        @orders[id] = order
+      end
+
+      def build_cart(id, requested_line_items, discount_codes, previous: nil)
+        line_items = build_line_items(requested_line_items)
+        discounts = discounts_for(discount_codes, previous&.discounts)
+        Portage::Ucp::Cart.new(id: id, line_items: line_items, currency: "USD",
+                               totals: totals_for(line_items, discounts), discounts: discounts)
+      end
+
+      def build_checkout(id, requested_line_items, discount_codes, fulfillment, status:, previous: nil)
+        line_items = build_line_items(requested_line_items)
+        discounts = discounts_for(discount_codes, previous&.discounts)
+        Portage::Ucp::Checkout.new(
+          id: id, status: status, line_items: line_items, currency: "USD",
+          totals: totals_for(line_items, discounts), links: [], discounts: discounts,
+          fulfillment: fulfillment || previous&.fulfillment || Portage::Ucp::CheckoutFulfillment.new
+        )
+      end
+
+      # Fixed 10% off, applied only for the well-known code "SAVE10" — enough
+      # for a conformance spec/adapter author to see a real AppliedDiscount
+      # round-trip without inventing a discount engine this adapter has no
+      # reason to model in full.
+      def discounts_for(discount_codes, previous)
+        return previous || Portage::Ucp::Discounts.new if discount_codes.nil?
+
+        applied = if discount_codes.include?("SAVE10")
+                    [Portage::Ucp::AppliedDiscount.new(title: "10% off",
+                                                       amount: 0, code: "SAVE10")]
+                  else
+                    []
+                  end
+        Portage::Ucp::Discounts.new(codes: discount_codes, applied: applied)
+      end
+
+      # `req[:product_id]` is looked up against the featured (first) variant
+      # — the same variant #search_catalog/#get_product would show as the
+      # listing default — since this in-memory adapter's fixtures are
+      # single-variant products and Item#id is spec'd as a variant id
+      # (types/variant.json: "Used as item.id in checkout"), not a product
+      # id.
+      def build_line_items(requested)
+        requested.map do |req|
+          product = @products.fetch(req[:product_id])
+          variant = product.variants.first
+          total = variant.price.amount * req[:quantity]
+          Portage::Ucp::LineItem.new(
+            id: next_id("li"),
+            item: Portage::Ucp::Item.new(id: variant.id, title: product.title, price: variant.price.amount),
+            quantity: req[:quantity],
+            totals: [Portage::Ucp::Total.new(type: "subtotal", amount: total),
+                     Portage::Ucp::Total.new(type: "total", amount: total)]
+          )
+        end
+      end
+
+      def totals_for(line_items, discounts)
+        subtotal = line_items.sum { |li| li.totals.find { |t| t.type == "total" }.amount }
+        discount_amount = discounts.applied.sum(&:amount)
+        [Portage::Ucp::Total.new(type: "subtotal", amount: subtotal),
+         Portage::Ucp::Total.new(type: "total", amount: subtotal - discount_amount)]
+      end
+
+      def zero_totals
+        [Portage::Ucp::Total.new(type: "subtotal", amount: 0), Portage::Ucp::Total.new(type: "total", amount: 0)]
+      end
+
+      def raise_if_any_line_out_of_stock!(checkout)
+        unavailable = checkout.line_items.select { |li| li.item.id.start_with?(OUT_OF_STOCK_PREFIX) }
+        return if unavailable.empty?
+
+        raise Portage::Ucp::OutOfStockError, "no longer available: #{unavailable.map { |li| li.item.title }.join(', ')}"
+      end
+
+      def next_id(prefix)
+        @next_id += 1
+        "#{prefix}_#{@next_id}"
+      end
+    end
+  end
+end

data/lib/portage/ucp/rspec.rb

@@ -0,0 +1,175 @@
+require "portage/ucp"
+
+module Portage
+  module Ucp
+    # Adapter conformance kit — design-log §17: "Nothing currently checks a
+    # third-party Adapter against the contract before its capability shows up
+    # in a manifest." `SchemaValidator` (see README, "Spec conformance")
+    # checks wire *shape*; this checks the behavioral guarantees §9 promises
+    # that schema-valid output can still violate — idempotency not actually
+    # deduped, a raw PAN reaching the adapter, a capability advertised whose
+    # own output doesn't round-trip through the schema it claims to speak.
+    #
+    # Not loaded by `require "portage/ucp"` — this pulls in RSpec itself,
+    # which the core gem otherwise has zero runtime dependency on (only a
+    # development one, per its own README). An adapter author's own spec
+    # suite opts in explicitly:
+    #
+    #   require "portage/ucp/rspec"
+    #
+    #   RSpec.describe MyAdapter do
+    #     it_behaves_like "a portage adapter" do
+    #       let(:adapter) { MyAdapter.new(client: my_test_client) }
+    #       let(:existing_product_id) { "known-good-product-id" }
+    #       # optional — only needed when a purchasable line item is a
+    #       # *different* id than the catalog product id (Shopify: a
+    #       # ProductVariant GID vs. the parent Product GID). Defaults to
+    #       # existing_product_id, which is correct for any backend where
+    #       # "the product" and "the thing you add to a cart" share one id.
+    #       # let(:existing_variant_id) { "known-good-purchasable-id" }
+    #       # optional — enables the out-of-stock example:
+    #       # let(:out_of_stock_product_id) { "known-sold-out-product-id" }
+    #     end
+    #   end
+    #
+    # `existing_product_id` must resolve to a real, in-stock, purchasable
+    # product against whatever backend `adapter` is wired to (a live
+    # sandbox store, or webmock/VCR stubs — this kit doesn't care which).
+    # Every example below skips itself when the adapter under test doesn't
+    # advertise the capability it needs, so a catalog/cart-only adapter
+    # (§16's Etsy/Instagram shape) still runs the kit cleanly.
+    module RSpec
+      module_function
+
+      def advertised?(adapter, capability_name)
+        capability = Portage::Ucp::CapabilityRegistry.default.find(capability_name)
+        capability&.advertised_for?(adapter)
+      end
+    end
+  end
+end
+
+RSpec.shared_examples "a portage adapter" do
+  let(:dispatcher) { Portage::Ucp::Dispatcher.new(adapter: adapter) }
+  let(:schema_validator) { Portage::Ucp::SchemaValidator.new }
+  let(:conformance_idempotency_key) { "conformance-#{object_id}-#{rand(1_000_000)}" }
+  let(:existing_variant_id) { existing_product_id }
+
+  def checkout_capability_advertised?
+    Portage::Ucp::RSpec.advertised?(adapter, "dev.ucp.shopping.checkout")
+  end
+
+  def catalog_capability_advertised?
+    Portage::Ucp::RSpec.advertised?(adapter, "dev.ucp.shopping.catalog")
+  end
+
+  def create_conformance_checkout(idempotency_key: conformance_idempotency_key)
+    dispatcher.call(
+      capability: "dev.ucp.shopping.checkout", action: "create_checkout",
+      arguments: { line_items: [{ product_id: existing_variant_id, quantity: 1 }],
+                   idempotency_key: idempotency_key }
+    )
+  end
+
+  it "produces a create_checkout response that validates against UCP's own checkout schema" do
+    skip "adapter does not advertise dev.ucp.shopping.checkout" unless checkout_capability_advertised?
+
+    response = create_conformance_checkout
+    errors = schema_validator.errors_for("schemas/shopping/checkout.json", response[:structuredContent])
+
+    expect(errors).to eq([]), "create_checkout's response doesn't validate: #{errors.join('; ')}"
+  end
+
+  # The core gem's own dedup table, when the adapter uses it (every bundled
+  # adapter includes `Support::Idempotency`). nil for an adapter that dedupes
+  # some other way — see the example below for why that costs it a check.
+  def conformance_dedup_table
+    return nil unless adapter.is_a?(Portage::Ucp::Support::Idempotency)
+
+    adapter.instance_variable_get(:@idempotency_results)
+  end
+
+  it "dedupes a repeated idempotency_key on create_checkout rather than re-running the mutation (§9a)" do
+    skip "adapter does not advertise dev.ucp.shopping.checkout" unless checkout_capability_advertised?
+
+    first = create_conformance_checkout
+    second = create_conformance_checkout
+
+    expect(second[:structuredContent]).to eq(first[:structuredContent]),
+                                          "a repeated idempotency_key produced a different result — " \
+                                          "the adapter isn't deduping mutating calls per §9a"
+
+    # Equal output is necessary but nowhere near sufficient, and this is the
+    # trap §17 named: an adapter wired to webmock/VCR stubs that answer every
+    # request with one fixed response returns identical output whether or not
+    # it deduped anything, so the assertion above passes for the wrong reason
+    # on exactly the test setup an adapter author is most likely to write.
+    # When the adapter uses `Support::Idempotency`, check the table itself —
+    # an adapter that never deduped has no entry under the key at all.
+    table = conformance_dedup_table
+    if table.nil?
+      warn "[portage conformance] #{adapter.class} doesn't include " \
+           "Portage::Ucp::Support::Idempotency, so dedup was only checked by output equality — " \
+           "which a fixed-response test double satisfies without deduping. Assert the dedup " \
+           "yourself (e.g. `expect(stub).to have_been_requested.once`) in your own spec."
+    else
+      expect(table).to include(conformance_idempotency_key),
+                       "create_checkout returned equal output for a repeated idempotency_key but recorded " \
+                       "nothing in the dedup table — the second call re-ran the mutation and only looked " \
+                       "deduped because the backend double answers every request identically (§9a)"
+    end
+  end
+
+  it "produces a search_catalog response that validates against UCP's own catalog search schema" do
+    skip "adapter does not advertise dev.ucp.shopping.catalog" unless catalog_capability_advertised?
+
+    response = dispatcher.call(capability: "dev.ucp.shopping.catalog", action: "search_catalog",
+                               arguments: { query: "", limit: 5 })
+    errors = schema_validator.errors_for("schemas/shopping/catalog_search.json#/$defs/search_response",
+                                         response[:structuredContent])
+
+    expect(errors).to eq([]), "search_catalog's response doesn't validate: #{errors.join('; ')}"
+  end
+
+  it "produces a get_product response that validates against UCP's own catalog lookup schema" do
+    skip "adapter does not advertise dev.ucp.shopping.catalog" unless catalog_capability_advertised?
+
+    response = dispatcher.call(capability: "dev.ucp.shopping.catalog", action: "get_product",
+                               arguments: { product_id: existing_product_id })
+    errors = schema_validator.errors_for("schemas/shopping/catalog_lookup.json#/$defs/get_product_response",
+                                         response[:structuredContent])
+
+    expect(errors).to eq([]), "get_product's response doesn't validate: #{errors.join('; ')}"
+  end
+
+  it "never lets a raw, Luhn-valid PAN reach the adapter's complete_checkout (§9's PCI boundary)" do
+    skip "adapter does not advertise dev.ucp.shopping.checkout" unless checkout_capability_advertised?
+
+    checkout_id = create_conformance_checkout[:structuredContent]["id"]
+    expect(adapter).not_to receive(:complete_checkout)
+
+    expect do
+      dispatcher.call(capability: "dev.ucp.shopping.checkout", action: "complete_checkout",
+                      arguments: { checkout_id: checkout_id, payment_token: "4242424242424242",
+                                   idempotency_key: "#{conformance_idempotency_key}-complete" })
+    end.to raise_error(Portage::Ucp::RawPanRejectedError)
+  end
+
+  it "raises Portage::Ucp::OutOfStockError from complete_checkout for a line that's gone out of stock" do
+    skip "no out_of_stock_product_id given — this example is opt-in" unless respond_to?(:out_of_stock_product_id)
+    skip "adapter does not advertise dev.ucp.shopping.checkout" unless checkout_capability_advertised?
+
+    checkout = dispatcher.call(
+      capability: "dev.ucp.shopping.checkout", action: "create_checkout",
+      arguments: { line_items: [{ product_id: out_of_stock_product_id, quantity: 1 }],
+                   idempotency_key: "#{conformance_idempotency_key}-oos" }
+    )
+
+    expect do
+      dispatcher.call(capability: "dev.ucp.shopping.checkout", action: "complete_checkout",
+                      arguments: { checkout_id: checkout[:structuredContent]["id"],
+                                   payment_token: "sptk_conformance_test_token",
+                                   idempotency_key: "#{conformance_idempotency_key}-oos-complete" })
+    end.to raise_error(Portage::Ucp::OutOfStockError)
+  end
+end

data/lib/portage/ucp/schema_validator.rb

@@ -20,11 +20,17 @@ module Portage
       end
 
       # @param relative_path [String] e.g. "schemas/shopping/cart.json", matching
-      #   the vendored path under schemas/<version>/.
+      #   the vendored path under schemas/<version>/. A path with a
+      #   `#/$defs/...` fragment (e.g.
+      #   "schemas/shopping/catalog_search.json#/$defs/search_response")
+      #   validates against that named subschema instead of the document
+      #   root — for schemas like catalog_search.json/catalog_lookup.json
+      #   that define several request/response shapes as siblings under
+      #   $defs rather than being one schema per file.
       # @return [Array<String>] human-readable validation error messages: empty
       #   means `data` conforms.
       def errors_for(relative_path, data)
-        schemer = JSONSchemer.schema(load(relative_path), ref_resolver: method(:resolve_ref))
+        schemer = JSONSchemer.schema(schema_for(relative_path), ref_resolver: method(:resolve_ref))
         schemer.validate(data).map { |error| JSONSchemer::Errors.pretty(error) }
       end
 
@@ -40,6 +46,21 @@ module Portage
 
       private
 
+      # A bare path loads and validates against the document root, same as
+      # before. A path carrying a fragment becomes a single-$ref schema
+      # pointing at that fragment, resolved the same way any other
+      # cross-document $ref in these vendored schemas is (via #resolve_ref) —
+      # $defs entries can themselves $ref sibling $defs by a local "#/..."
+      # pointer (catalog_lookup.json's get_product_response -> #/$defs/
+      # detail_product being one), so the fragment must be resolved by the
+      # schema library against the whole loaded document, not sliced out of
+      # it here.
+      def schema_for(relative_path)
+        return load(relative_path) unless relative_path.include?("#")
+
+        { "$ref" => "#{@base_url}#{relative_path}" }
+      end
+
       def resolve_ref(uri)
         relative_path = uri.to_s.delete_prefix(@base_url).sub(/#.*/, "")
         load(relative_path)

data/lib/portage/ucp/support/api_error.rb

@@ -6,16 +6,19 @@ module Portage
       # everything the Wix gem raises) — a module rather than a base class
       # precisely to leave that hierarchy alone.
       #
-      # Carries the two things every gem's ApiError carried identically: the
-      # HTTP status (which Support::NotFound#nil_on_not_found reads) and the parsed
-      # body. What differs per platform is only where the human-readable
-      # message lives inside that body, which is the `detail` hook.
+      # Carries the three things every gem's ApiError carried identically: the
+      # HTTP status (which Support::NotFound#nil_on_not_found reads), the
+      # parsed body, and — when the response sent one — the Retry-After
+      # header Support::Retry consults to time a 429's backoff. What differs
+      # per platform is only where the human-readable message lives inside
+      # the body, which is the `detail` hook.
       module ApiError
-        attr_reader :status, :body
+        attr_reader :status, :body, :retry_after
 
-        def initialize(status, body)
+        def initialize(status, body, retry_after: nil)
           @status = status
           @body = body
+          @retry_after = retry_after
           super("#{api_label} API error (#{status}): #{detail(body)}")
         end
 

data/lib/portage/ucp/support/http_client.rb

@@ -40,9 +40,16 @@ module Portage
         # answer a successful DELETE with 204 and no content at all.
         def parse!(response)
           parsed = response.body.nil? || response.body.empty? ? {} : JSON.parse(response.body)
-          raise api_error_class.new(response.code.to_i, parsed) unless response.is_a?(Net::HTTPSuccess)
+          return parsed if response.is_a?(Net::HTTPSuccess)
 
-          parsed
+          status = response.code.to_i
+          # 409 means "you lost a race with a concurrent write" the same way
+          # on every REST platform behind this module — normalized here to
+          # Portage::Ucp::ConflictError rather than each gem's own ApiError,
+          # since it's cross-cutting, not platform-specific (see errors.rb).
+          raise Portage::Ucp::ConflictError, "conflict (409): #{parsed}" if status == 409
+
+          raise api_error_class.new(status, parsed, retry_after: response["Retry-After"])
         end
 
         def api_error_class

data/lib/portage/ucp/support/idempotency.rb

@@ -12,13 +12,32 @@ module Portage
       # workers needs a shared store, which is a consumer concern the same
       # way RateLimiter is.
       module Idempotency
+        # Guards lazy init of each instance's lock table below — brief and
+        # only touched once per instance, not on the hot dedup path.
+        INIT_MUTEX = Mutex.new
+
         private
 
         def dedup(idempotency_key)
-          @idempotency_results ||= {}
-          return @idempotency_results[idempotency_key] if @idempotency_results.key?(idempotency_key)
+          init_idempotency_locks!
+
+          key_lock = @idempotency_mutex.synchronize { @idempotency_locks[idempotency_key] ||= Mutex.new }
+
+          key_lock.synchronize do
+            return @idempotency_results[idempotency_key] if @idempotency_results.key?(idempotency_key)
+
+            @idempotency_results[idempotency_key] = yield
+          end
+        end
+
+        def init_idempotency_locks!
+          return if @idempotency_mutex
 
-          @idempotency_results[idempotency_key] = yield
+          INIT_MUTEX.synchronize do
+            @idempotency_mutex ||= Mutex.new
+            @idempotency_results ||= {}
+            @idempotency_locks ||= {}
+          end
         end
       end
     end

data/lib/portage/ucp/support/retry.rb

@@ -0,0 +1,66 @@
+module Portage
+  module Ucp
+    module Support
+      # Bounded exponential backoff + jitter around a single upstream call.
+      #
+      # #with_retry is only ever safe to wrap around a call that is either
+      # naturally idempotent (a read) or already sitting inside a
+      # Support::Idempotency#dedup block (a mutation memoized by
+      # idempotency_key) — every bundled adapter's mutating method already
+      # dedups, so its Client-level HTTP/GraphQL calls satisfy this by
+      # construction. Retrying a non-idempotent mutation that ISN'T inside
+      # dedup can double it up: a request that partially applied upstream
+      # before the connection dropped gets reapplied on retry. Never call
+      # #with_retry around a bare mutation outside dedup.
+      #
+      # Only retries signals that mean "the upstream didn't do the work, try
+      # again": HTTP 429 (honoring Retry-After when present), 5xx, and
+      # platform-specific throttling (Shopify's GraphQL THROTTLED code,
+      # cartSubmitForCompletion's SubmitThrottled pollAfter) via
+      # #retryable_error? overrides. Everything else — 4xx business
+      # rejections, UserError, OutOfStockError, ConflictError — passes
+      # straight through un-retried.
+      module Retry
+        DEFAULT_MAX_ATTEMPTS = 4
+        DEFAULT_BASE_DELAY = 0.25
+        DEFAULT_MAX_DELAY = 4.0
+
+        private
+
+        def with_retry(max_attempts: DEFAULT_MAX_ATTEMPTS, base_delay: DEFAULT_BASE_DELAY,
+                       max_delay: DEFAULT_MAX_DELAY)
+          attempt = 0
+
+          begin
+            attempt += 1
+            yield
+          rescue StandardError => e
+            raise unless retryable_error?(e)
+            raise if attempt >= max_attempts
+
+            sleep(retry_delay(e, attempt, base_delay, max_delay))
+            retry
+          end
+        end
+
+        # Default covers the common REST shape: any error carrying a `status`
+        # of 429 or 5xx (Support::ApiError-including errors all expose this).
+        # Platform clients override to recognize signals with no HTTP status
+        # of their own (e.g. a GraphQL THROTTLED extension code).
+        def retryable_error?(error)
+          error.respond_to?(:status) && (error.status == 429 || (500..599).cover?(error.status))
+        end
+
+        # Honors an upstream Retry-After (seconds) when the error carries
+        # one; otherwise backs off exponentially with full jitter.
+        def retry_delay(error, attempt, base_delay, max_delay)
+          retry_after = error.respond_to?(:retry_after) ? error.retry_after : nil
+          return [retry_after.to_f, 0].max if retry_after
+
+          exponential = [base_delay * (2**(attempt - 1)), max_delay].min
+          rand * exponential
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/support/session_lock.rb

@@ -0,0 +1,40 @@
+module Portage
+  module Ucp
+    module Support
+      # §21: multi-call mutations (read-modify-write against Shopify's
+      # Storefront API, or the equivalent REST sequence on Wix) aren't
+      # atomic upstream, so two concurrent calls against the same cart or
+      # checkout id can interleave and drop each other's writes — not just
+      # a lost update, lines vanish. This serializes calls per id so a
+      # concurrent duplicate waits for the first to finish instead of
+      # racing it.
+      #
+      # In-process only, same caveat as RateLimiter and Idempotency: a
+      # multi-process deployment needs a shared lock, which is a consumer
+      # concern. Keep #synchronize as the only method a consumer touches so
+      # a Redis-backed replacement can drop in without adapters changing.
+      module SessionLock
+        INIT_MUTEX = Mutex.new
+
+        private
+
+        def synchronize(session_id)
+          init_session_locks!
+
+          key_lock = @session_lock_mutex.synchronize { @session_locks[session_id] ||= Mutex.new }
+
+          key_lock.synchronize { yield }
+        end
+
+        def init_session_locks!
+          return if @session_lock_mutex
+
+          INIT_MUTEX.synchronize do
+            @session_lock_mutex ||= Mutex.new
+            @session_locks ||= {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/value_objects.rb

@@ -1,9 +1,169 @@
 module Portage
   module Ucp
     # Internal arithmetic helper only — never appears in a wire shape directly.
+    # Cart/Checkout/Order totals are bare minor-unit integers (Total#amount)
+    # once they reach a value object; Money exists so Support::Amounts has
+    # somewhere to hand back both the minor-unit amount and its currency
+    # together mid-conversion. Product/Variant carry currency-bearing wire
+    # fields directly (Price, below) rather than through Money.
     Money = Data.define(:amount_minor, :currency)
 
-    Product = Data.define(:id, :title, :description, :price, :available, :variants, :url)
+    # schemas/shopping/types/price.json — the wire-shape counterpart to Money
+    # above: an integer minor-unit amount paired with its currency, appearing
+    # directly in Product/Variant payloads.
+    Price = Data.define(:amount, :currency) do
+      def to_wire_h = { "amount" => amount, "currency" => currency }
+    end
+
+    # schemas/shopping/types/price_range.json
+    PriceRange = Data.define(:min, :max) do
+      def to_wire_h = { "min" => min.to_wire_h, "max" => max.to_wire_h }
+    end
+
+    # schemas/shopping/types/description.json — the spec requires at least
+    # one of plain/html/markdown; that's a request-time authoring concern
+    # this value object doesn't enforce, same posture as PostalAddress
+    # leaving every field optional.
+    Description = Data.define(:plain, :html, :markdown) do
+      def initialize(plain: nil, html: nil, markdown: nil) = super
+
+      def to_wire_h = { "plain" => plain, "html" => html, "markdown" => markdown }.compact
+    end
+
+    # schemas/shopping/types/category.json
+    Category = Data.define(:value, :taxonomy) do
+      def initialize(value:, taxonomy: nil) = super
+
+      def to_wire_h = { "value" => value, "taxonomy" => taxonomy }.compact
+    end
+
+    # schemas/shopping/types/media.json
+    Media = Data.define(:type, :url, :alt_text, :width, :height) do
+      def initialize(type:, url:, alt_text: nil, width: nil, height: nil) = super
+
+      def to_wire_h
+        { "type" => type, "url" => url, "alt_text" => alt_text, "width" => width, "height" => height }.compact
+      end
+    end
+
+    # schemas/shopping/types/option_value.json — a selectable value for a
+    # ProductOption (e.g. "Blue" under "Color").
+    OptionValue = Data.define(:id, :label) do
+      def initialize(label:, id: nil) = super
+
+      def to_wire_h = { "id" => id, "label" => label }.compact
+    end
+
+    # schemas/shopping/types/product_option.json
+    ProductOption = Data.define(:name, :values) do
+      def to_wire_h = { "name" => name, "values" => values.map(&:to_wire_h) }
+    end
+
+    # schemas/shopping/types/selected_option.json — which OptionValue a
+    # Variant actually carries for a given option (e.g. Size: Large).
+    SelectedOption = Data.define(:name, :id, :label) do
+      def initialize(name:, label:, id: nil) = super
+
+      def to_wire_h = { "name" => name, "id" => id, "label" => label }.compact
+    end
+
+    # schemas/shopping/types/rating.json
+    Rating = Data.define(:value, :scale_max, :scale_min, :count) do
+      def initialize(value:, scale_max:, scale_min: 1, count: nil) = super
+
+      def to_wire_h
+        { "value" => value, "scale_min" => scale_min, "scale_max" => scale_max, "count" => count }.compact
+      end
+    end
+
+    # schemas/shopping/types/variant.json — a purchasable variant of a
+    # Product. `id` is what LineItem#item.id actually references at
+    # checkout, not Product#id.
+    # `barcodes` and `availability` are left as plain wire-shaped hashes
+    # (`{"type" =>, "value" =>}` / `{"available" =>, "status" =>}`) rather
+    # than their own Data types — both are simple, spec doesn't name them as
+    # standalone $refs, and the parent's `to_wire_h` needs them exactly as
+    # given, same posture as Adjustment#line_items' inline hashes.
+    Variant = Data.define(:id, :title, :description, :price, :sku, :barcodes, :list_price, :availability, :options,
+                          :media, :tags, :metadata) do
+      def initialize(id:, title:, description:, price:, sku: nil, barcodes: [], list_price: nil, availability: nil,
+                     options: [], media: [], tags: [], metadata: nil)
+        super
+      end
+
+      def to_wire_h
+        { "id" => id, "title" => title, "description" => description.to_wire_h,
+          "price" => price.to_wire_h }.merge(optional_wire_h)
+      end
+
+      private
+
+      def optional_wire_h
+        h = { "sku" => sku, "list_price" => list_price&.to_wire_h, "availability" => availability }.compact
+        h["barcodes"] = barcodes unless barcodes.empty?
+        h["options"] = options.map(&:to_wire_h) unless options.empty?
+        h["media"] = media.map(&:to_wire_h) unless media.empty?
+        h["tags"] = tags unless tags.empty?
+        h["metadata"] = metadata if metadata
+        h
+      end
+    end
+
+    # schemas/shopping/types/product.json — requires id/title/description/
+    # price_range/variants (variants minItems: 1). `metadata` is the spec's
+    # own sanctioned extension point for business-defined custom data
+    # (Shopify/Wix metafields etc.) — see Portage::Ucp::Shopify.configure's
+    # metadata_field.
+    Product = Data.define(:id, :title, :description, :price_range, :variants, :handle, :url, :categories,
+                          :list_price_range, :media, :options, :tags, :metadata, :rating) do
+      def initialize(id:, title:, description:, price_range:, variants:, handle: nil, url: nil, categories: [],
+                     list_price_range: nil, media: [], options: [], tags: [], metadata: nil, rating: nil)
+        super
+      end
+
+      def to_wire_h
+        { "id" => id, "title" => title, "description" => description.to_wire_h,
+          "price_range" => price_range.to_wire_h, "variants" => variants.map(&:to_wire_h) }.merge(optional_wire_h)
+      end
+
+      private
+
+      def optional_wire_h
+        h = { "handle" => handle, "url" => url, "list_price_range" => list_price_range&.to_wire_h,
+              "metadata" => metadata, "rating" => rating&.to_wire_h }.compact
+        h["categories"] = categories.map(&:to_wire_h) unless categories.empty?
+        h["media"] = media.map(&:to_wire_h) unless media.empty?
+        h["options"] = options.map(&:to_wire_h) unless options.empty?
+        h["tags"] = tags unless tags.empty?
+        h
+      end
+    end
+
+    # schemas/shopping/catalog_search.json#/$defs/search_response — the
+    # container Adapter#search_catalog actually returns; `products` alone
+    # isn't schema-conformant (search_response requires `ucp` + `products` at
+    # the top level, not a bare array). `messages` entries are left as plain
+    # wire-shaped hashes, same rationale as Variant#barcodes above.
+    CatalogSearchResult = Data.define(:products, :messages) do
+      def initialize(products:, messages: []) = super
+
+      def to_wire_h
+        h = { "products" => products.map(&:to_wire_h) }
+        h["messages"] = messages unless messages.empty?
+        h
+      end
+    end
+
+    # schemas/shopping/catalog_lookup.json#/$defs/get_product_response — the
+    # container Adapter#get_product returns when the product is found (nil
+    # otherwise, same not-found posture as get_cart/get_checkout/get_order).
+    # Doesn't model detail_product's `selected`/`options` availability-signal
+    # extension (interactive variant narrowing) — Adapter#get_product's
+    # signature has no `selected:`/`preferences:` params to source it from
+    # yet; unresearched, same status as design-log §16's other backlog items.
+    ProductDetail = Data.define(:product) do
+      def to_wire_h = { "product" => product.to_wire_h }
+    end
 
     # One cost-breakdown entry (schemas/shopping/types/total.json). `amount` is a
     # signed integer in the parent object's currency's minor units.

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.2.0".freeze
+    VERSION = "0.3.0".freeze
   end
 end

data/lib/portage/ucp/wire_envelope.rb

@@ -11,7 +11,11 @@ module Portage
       ENVELOPES = {
         "dev.ucp.shopping.cart" => -> { { "version" => SPEC_VERSION } },
         "dev.ucp.shopping.checkout" => -> { { "version" => SPEC_VERSION, "payment_handlers" => {} } },
-        "dev.ucp.shopping.order" => -> { { "version" => SPEC_VERSION } }
+        "dev.ucp.shopping.order" => -> { { "version" => SPEC_VERSION } },
+        # response_catalog_schema (catalog_search.json's search_response and
+        # catalog_lookup.json's get_product_response both require it) — same
+        # minimal shape as cart/order, no capability-specific extra field.
+        "dev.ucp.shopping.catalog" => -> { { "version" => SPEC_VERSION } }
       }.freeze
 
       def self.wrap(capability_name, payload_hash)

data/lib/portage/ucp.rb

@@ -13,6 +13,9 @@ require_relative "ucp/support/totals"
 require_relative "ucp/support/line_item_status"
 require_relative "ucp/support/idempotency"
 require_relative "ucp/support/checkout_state"
+require_relative "ucp/support/session_lock"
+require_relative "ucp/support/retry"
+require_relative "ucp/reference_adapter"
 require_relative "ucp/support/api_error"
 require_relative "ucp/support/not_found"
 require_relative "ucp/support/http_client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tom Whitbread
@@ -170,7 +170,9 @@ files:
 - lib/portage/ucp/rack/manifest_endpoint.rb
 - lib/portage/ucp/rack/webhook_endpoint.rb
 - lib/portage/ucp/rate_limiter.rb
+- lib/portage/ucp/reference_adapter.rb
 - lib/portage/ucp/resolver.rb
+- lib/portage/ucp/rspec.rb
 - lib/portage/ucp/schema_validator.rb
 - lib/portage/ucp/support/amounts.rb
 - lib/portage/ucp/support/api_error.rb
@@ -179,6 +181,8 @@ files:
 - lib/portage/ucp/support/idempotency.rb
 - lib/portage/ucp/support/line_item_status.rb
 - lib/portage/ucp/support/not_found.rb
+- lib/portage/ucp/support/retry.rb
+- lib/portage/ucp/support/session_lock.rb
 - lib/portage/ucp/support/token_exchange.rb
 - lib/portage/ucp/support/totals.rb
 - lib/portage/ucp/value_objects.rb
@@ -275,7 +279,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Expose a commerce backend to AI shopping agents over MCP and UCP
 test_files: []