portage-ucp 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9198c70ed7abc380268adc344d7496c049a3c78c0ed28b16944e3b27d9d01ba
-  data.tar.gz: c076c1b4e544825d0db160bf2453fed3e256b2024c7aafb8f431227ec22364ef
+  metadata.gz: 8ce343c7abccfbe4c1a8cf2ed0db6340d588c770e959fef42aec644ef6a69800
+  data.tar.gz: 7d1a96bb2e150b822c1dedbe95b8b3f14fbced7d6be9b5287e120e3e8152059f
 SHA512:
-  metadata.gz: 80aac639014575e4416c3e477f451bf9cb25b3cd69ab8a3cda512bd19243d51a95b54c5086b738fc9140be4e0318cb17b81a30767f2ba6b18546b6cd22e9a33b
-  data.tar.gz: dc0f578ee8d379f9f12c4605dcaf37757d5518f2764087186669a4809773b5bd869192328a0027ef61fd36f5a4dbc629697841e57f9065c96a9a5d5d7796c11a
+  metadata.gz: 0cd44b69ef19d804c91696b6477e3616eb9dd64c326754f5ff7f142ff494bdaf42b1bd4686888dcb1d7c6e6198b737cc501384278a9a6d2441173b6191029eab
+  data.tar.gz: 22a096bb7ab8cfaa6285ad12b8c5dfd8098c40f4f538115688e03ad5eac59273f16eca247d1409e28f8f30c730d9ef7cb7c7a5d19586bdacb0c0f002f0b61e9a

data/CHANGELOG.md

@@ -4,7 +4,81 @@ 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.1.0] - Unreleased
+## [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`
+  (design-log §16 "Stock/availability going stale") now documents that
+  adapters should raise it when the platform rejects completion over a
+  no-longer-available line item, instead of re-checking with a separate call
+  agents could forget to make.
+- `Adapter#cancel_order`, `#request_return`, `#refund_order` — a gem-side
+  extension of `dev.ucp.shopping.order` (design-log §16 "Order changes"),
+  since the real UCP spec's order lifecycle is get-only. Each returns the
+  updated `Order`, with the change recorded as an appended
+  `Portage::Ucp::Adjustment`.
+- `Capability#predicate` — a minimal escape hatch for extensions that add
+  fields rather than actions (`dev.ucp.shopping.discount`,
+  `dev.ucp.shopping.fulfillment`): a capability can name an adapter method
+  instead of an action set, and `#advertised_for?` asks it directly.
+  `create_cart`/`update_cart`/`create_checkout`/`update_checkout` gain an
+  optional `discount_codes:` param defaulting to `nil` (not `[]`), so "not
+  mentioned" and "clear the codes" stay distinguishable.
+- `dev.ucp.shopping.fulfillment` — the vendored extension for picking a
+  shipping method/rate or pickup location during checkout. New value objects
+  `PostalAddress`, `ShippingDestination`, `RetailLocation`,
+  `FulfillmentOption`, `FulfillmentGroup`, `FulfillmentMethod`, and the
+  `CheckoutFulfillment` container (named apart from `Fulfillment`, which
+  Order's post-purchase container already owns — see design-log).
+
+## [0.1.0] - 2026-08-14
 
 - Initial pre-release. Protocol-only core: `Adapter` contract, capability
   registry, manifest builder, MCP server wrapper, offline `SchemaValidator`,

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) ---
@@ -17,24 +19,53 @@ module Portage
       # builds the response's Item/Total/LineItem itself.
       # @return [Portage::Ucp::Cart]
       def get_cart(cart_id:) = not_implemented
+      # `discount_codes:` is the dev.ucp.shopping.discount extension — nil
+      # (the default) means the request didn't touch discounts at all; an
+      # adapter that doesn't override #discount_codes_supported? never sees
+      # anything but nil here (see below). Full-replacement like line_items:
+      # once codes are involved, [] clears them, same as UCP's own
+      # discounts_object semantics.
       # @return [Portage::Ucp::Cart]
-      def create_cart(line_items:, idempotency_key:) = not_implemented
+      def create_cart(line_items:, idempotency_key:, discount_codes: nil) = not_implemented
       # @return [Portage::Ucp::Cart]
-      def update_cart(cart_id:, line_items:, idempotency_key:) = not_implemented
+      def update_cart(cart_id:, line_items:, idempotency_key:, discount_codes: nil) = not_implemented
       # @return [Portage::Ucp::Cart]
       def cancel_cart(cart_id:, idempotency_key:) = not_implemented
 
       # --- Checkout (dev.ucp.shopping.checkout) ---
+      # `discount_codes:` carries the same dev.ucp.shopping.discount
+      # semantics as create_cart/update_cart above.
+      # `fulfillment:` is the dev.ucp.shopping.fulfillment extension — nil
+      # (the default) means the request didn't touch fulfillment at all; an
+      # adapter that doesn't override #fulfillment_supported? never sees
+      # anything but nil here (see below). On create it carries the agent's
+      # desired methods (type + line_item_ids per shipping/pickup group —
+      # `Portage::Ucp::FulfillmentMethod#id`/`#destinations`/`#groups` are
+      # omitted since the merchant generates those); on update it carries the
+      # agent's `selected_destination_id`/`selected_option_id` choices against
+      # the methods/groups the merchant already returned.
       # @return [Portage::Ucp::Checkout]
-      def create_checkout(line_items:, idempotency_key:) = not_implemented
+      def create_checkout(line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil) = not_implemented
       # @return [Portage::Ucp::Checkout]
       def get_checkout(checkout_id:) = not_implemented
+
       # Full-replacement, same as update_cart — line_items is required on
       # checkout update per the real spec.
       # @return [Portage::Ucp::Checkout]
-      def update_checkout(checkout_id:, line_items:, idempotency_key:) = not_implemented
+      def update_checkout(checkout_id:, line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil)
+        not_implemented
+      end
+
       # @param payment_token [String] single-use token from a UCP payment handler / AP2
       #   exchange — NEVER a raw PAN.
+      # Re-checks stock at the point of committing money, since search_catalog/
+      # get_product (dev.ucp.shopping.catalog) don't promise live inventory and
+      # nothing else re-checks between browsing and buying. An adapter whose
+      # platform rejects completion because a line item is out of stock or
+      # otherwise unavailable should raise Portage::Ucp::OutOfStockError rather
+      # 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
       # @return [Portage::Ucp::Checkout]
       def complete_checkout(checkout_id:, payment_token:, idempotency_key:) = not_implemented
       # @return [Portage::Ucp::Checkout]
@@ -43,6 +74,37 @@ module Portage
       # --- Order (dev.ucp.shopping.order) ---
       # @return [Portage::Ucp::Order, nil]
       def get_order(order_id:) = not_implemented
+      # Cancels a placed order. `reason` is an optional human-readable note,
+      # not a closed enum — the platform-specific enum mapping (if any) is an
+      # adapter concern.
+      # @return [Portage::Ucp::Order]
+      def cancel_order(order_id:, idempotency_key:, reason: nil) = not_implemented
+      # Requests a return for one or more order line items. `line_items` is an
+      # array of request-shaped hashes (`{id:, quantity:}`, unsigned) — same
+      # request/response asymmetry as `create_cart`'s `line_items:`. A return
+      # is a request the merchant still has to process; it shows up as a
+      # `pending` `Portage::Ucp::Adjustment` until they do.
+      # @return [Portage::Ucp::Order]
+      def request_return(order_id:, line_items:, idempotency_key:, reason: nil) = not_implemented
+      # Refunds one or more order line items.
+      # @return [Portage::Ucp::Order]
+      def refund_order(order_id:, line_items:, idempotency_key:, reason: nil) = not_implemented
+
+      # --- Discount (dev.ucp.shopping.discount) ---
+      # Extends Cart/Checkout with the `discount_codes:` param above rather
+      # than adding actions of its own — Capability::DISCOUNT advertises off
+      # this predicate instead of an overridden action method, since there's
+      # no dedicated method for #advertised_for? to detect an override on.
+      # @return [Boolean]
+      def discount_codes_supported? = false
+
+      # --- Fulfillment (dev.ucp.shopping.fulfillment) ---
+      # Extends Checkout with the `fulfillment:` param above rather than
+      # adding actions of its own — Capability::FULFILLMENT advertises off
+      # this predicate instead of an overridden action method, same rationale
+      # as #discount_codes_supported? above.
+      # @return [Boolean]
+      def fulfillment_supported? = false
 
       # --- Identity Linking (dev.ucp.shopping.identity, OAuth 2.0) ---
       # @return [Portage::Ucp::Identity] linked profile for an exchanged OAuth token

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

@@ -0,0 +1,16 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # schemas/shopping/discount.json — extends Cart/Checkout with a
+      # `discounts` field rather than adding actions of its own, so `actions`
+      # is empty and advertisement runs off Adapter#discount_codes_supported?
+      # instead (see Capability#advertised_for?).
+      DISCOUNT = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.discount",
+        version: "1",
+        actions: {},
+        predicate: :discount_codes_supported?
+      )
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # schemas/shopping/fulfillment.json — extends Checkout with a
+      # `fulfillment` field (shipping/pickup methods, groups, destinations)
+      # rather than adding actions of its own, same predicate-based
+      # advertisement as DISCOUNT above.
+      FULFILLMENT = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.fulfillment",
+        version: "1",
+        actions: {},
+        predicate: :fulfillment_supported?
+      )
+    end
+  end
+end

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

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

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

@@ -4,7 +4,12 @@ module Portage
       ORDER = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.order",
         version: "1",
-        actions: { "get_order" => :get_order }
+        actions: {
+          "get_order" => :get_order,
+          "cancel_order" => :cancel_order,
+          "request_return" => :request_return,
+          "refund_order" => :refund_order
+        }
       )
     end
   end

data/lib/portage/ucp/capability.rb

@@ -5,15 +5,25 @@ module Portage
     class Capability
       attr_reader :name, :version, :actions
 
-      def initialize(name:, version:, actions:)
+      # `predicate:` is for extension capabilities like
+      # dev.ucp.shopping.discount and dev.ucp.shopping.fulfillment that add a
+      # param to an existing action rather than an action of their own —
+      # there's no dedicated method whose override signals support, so the
+      # adapter exposes a boolean method instead and the capability asks it
+      # directly rather than inspecting `actions`.
+      def initialize(name:, version:, actions:, predicate: nil)
         @name = name
         @version = version
         @actions = actions
+        @predicate = predicate
       end
 
-      # Advertised only if at least one backing Adapter method is overridden —
+      # Advertised if the predicate says so, or (for ordinary action-based
+      # capabilities) if at least one backing Adapter method is overridden —
       # see Portage::Ucp::Adapter for why (contract can grow without breaking adapters).
       def advertised_for?(adapter)
+        return adapter.public_send(@predicate) if @predicate
+
         actions.values.any? { |method_name| overridden?(adapter, method_name) }
       end
 

data/lib/portage/ucp/errors.rb

@@ -8,5 +8,35 @@ module Portage
     class AuthenticationError < Error; end
     class RawPanRejectedError < 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 —
+    # design-log §16 "Stock/availability going stale": the gem re-checks by
+    # surfacing the platform's own rejection rather than adding a separate
+    # check_availability call agents could forget to make. Maps to UCP's
+    # 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