portage-ucp 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ce343c7abccfbe4c1a8cf2ed0db6340d588c770e959fef42aec644ef6a69800
-  data.tar.gz: 7d1a96bb2e150b822c1dedbe95b8b3f14fbced7d6be9b5287e120e3e8152059f
+  metadata.gz: 36c3a77e9f625761b827d1e925d54217b7bff302f4a7a60540d4a8c5d1794fb9
+  data.tar.gz: 05a86e2740a327c63bb0e06aa450e2aa5207aa60ce637575133483ed8df4698b
 SHA512:
-  metadata.gz: 0cd44b69ef19d804c91696b6477e3616eb9dd64c326754f5ff7f142ff494bdaf42b1bd4686888dcb1d7c6e6198b737cc501384278a9a6d2441173b6191029eab
-  data.tar.gz: 22a096bb7ab8cfaa6285ad12b8c5dfd8098c40f4f538115688e03ad5eac59273f16eca247d1409e28f8f30c730d9ef7cb7c7a5d19586bdacb0c0f002f0b61e9a
+  metadata.gz: d0d4746f829e60009463ee2748ba5c46ff6f3932b5a345f3f26d94e437a5132b39002945bf19abe1ee3d02c46e1760b52afa6910a15531df494c4e39dcca7787
+  data.tar.gz: 60898e67d72f545c24970415775506be4930336a4f325be61714cef0f810547f77b79951f7b48e3fb32b72cdd9adb9669b4f3af4f872be0a4bcb7ea60b325bf5

data/CHANGELOG.md

@@ -4,6 +4,69 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [Unreleased]
+
+## [0.4.0] - 2026-08-28
+
+- Added `Adapter#reorder(order_id:, idempotency_key:)`, advertised as a new
+  `app.portage-ucp.reorder` capability — a Portage extension, not part of the
+  UCP spec. Hydrates a `Cart` from a previous order's line items, re-checking
+  each item's current price/availability rather than replaying the order's
+  historical totals, and reports anything no longer purchasable via the new
+  `ReorderResult#unavailable_items` rather than failing the whole call.
+  Implemented in `ReferenceAdapter` as a worked example.
+- `Mcp::Server.call_tool` now emits a minimal pre-auth `tool_call_received`
+  event (capability, action, correlation id — no arguments) before
+  `authorize`/`rate_limit` run, moving the full `tool_called` event
+  (arguments included) below them. Previously the full event, arguments and
+  all, was logged before authorization, so an unauthenticated caller could
+  write attacker-chosen content into the operator's logs at whatever volume
+  the rate limiter would otherwise have refused (design-log §23).
+- `Mcp::Server.correlation_id_for` stamps both events with a correlation id
+  read from the inbound W3C `traceparent` in `server_context[:_meta]`
+  (SEP-414, `MCP::TraceContext`), falling back to `SecureRandom.uuid` when
+  absent or malformed. Deliberately per-request, not per-session —
+  `Server::Context` is built once per process in `.build`, and `mcp`
+  0.25.0's Streamable HTTP transport is stateful and multi-session, so
+  memoizing an id there would stamp every session in the process with the
+  same value (design-log §23). Because `traceparent` is unauthenticated
+  input read before `authorize`/`rate_limit` run, it's validated against
+  the W3C Trace Context format before use rather than accepted as-is — a
+  malformed or oversized value falls back to a generated id instead of
+  reaching the pre-auth log or `Dispatcher`/`CheckoutState` unchecked.
+- `Dispatcher` now threads its logger and each call's correlation id to the
+  adapter for the duration of that one call
+  (`Support::CheckoutState.with_observability`) so a
+  `checkout_state_transition` event (§12) fires from `record_checkout_status`
+  carrying the same correlation id as the `tool_called` event that triggered
+  it — without adding a `correlation_id:` kwarg to any checkout method, which
+  would have been a breaking change to the `Adapter` contract. Storage is
+  `Thread.current`, keyed per adapter object and restored on exit, rather
+  than an instance variable on the adapter: `Mcp::Server.build` constructs
+  one adapter per process, shared across every concurrent session, so an
+  instance variable would let two in-flight requests clobber each other's
+  correlation id — the same per-process-state trap §23 diagnosed for the
+  correlation id generator itself, one layer down. No `capability_negotiated`
+  event yet: `CapabilityNegotiator#negotiate` has no call site anywhere in
+  the gem outside its own spec, so there's nowhere to emit it from without
+  building that call site first (design-log §23).
+- `Observability::REDACTED_KEYS` grows past the three credential keys to
+  cover the PII that actually flows through logged events — `email`
+  (`Identity`, §3) and `first_name`/`last_name`/`phone_number`/
+  `street_address`/`extended_address`/`address_locality`/`address_region`/
+  `address_country`/`postal_code` (`PostalAddress`, fulfillment
+  destinations). §12's "Money-adjacent PII" named no real key — `Money`/
+  `Total` carry only amounts and currency codes (design-log §23 step 4).
+- `Rack::WebhookEndpoint` takes a `logger:` kwarg (defaulting to
+  `Portage::Ucp.configuration.logger`) and emits `order_webhook_received`
+  (order id, checkout id) on a verified payload and `order_webhook_rejected`
+  (reason: `invalid_signature` or `bad_request`) on the two rejection paths
+  — never the request body. No new `config.event_sink`: this endpoint is a
+  plain Rack app never built through `Mcp::Server.build`, so it can't reach
+  `mcp`'s own request hooks, and threading the gem's existing `logger:`
+  convention through one more constructor was the whole fix (design-log
+  §23 step 5).
+
 ## [0.3.0] - 2026-08-27
 
 - `Portage::Ucp::Support::Retry` (`lib/portage/ucp/support/retry.rb`) —

data/lib/portage/ucp/adapter.rb

@@ -90,6 +90,19 @@ module Portage
       # @return [Portage::Ucp::Order]
       def refund_order(order_id:, line_items:, idempotency_key:, reason: nil) = not_implemented
 
+      # --- Reorder (app.portage-ucp.reorder — Portage extension, not part of
+      # the UCP spec: dev.ucp.dev has no reorder/cart-hydration capability as
+      # of the 2026-04-08 spec) ---
+      # Hydrates a cart from a previous order's line items so a caller doesn't
+      # have to re-walk get_order + create_cart itself. Re-checks each item's
+      # current price/availability rather than replaying the order's snapshot
+      # totals — order_line_item.json's totals are historical, not live, same
+      # posture as complete_checkout's stock re-check above — and drops
+      # anything no longer purchasable instead of failing the whole call,
+      # reporting what got dropped via ReorderResult#unavailable_items.
+      # @return [Portage::Ucp::ReorderResult, nil] nil if the order isn't found.
+      def reorder(order_id:, idempotency_key:) = not_implemented
+
       # --- Discount (dev.ucp.shopping.discount) ---
       # Extends Cart/Checkout with the `discount_codes:` param above rather
       # than adding actions of its own — Capability::DISCOUNT advertises off

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, DISCOUNT, FULFILLMENT].freeze
+      ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT, REORDER].freeze
     end
   end
 end

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

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

data/lib/portage/ucp/capability_negotiator.rb

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

data/lib/portage/ucp/dispatcher.rb

@@ -4,12 +4,21 @@ module Portage
     # through the CapabilityRegistry to the backing Adapter method, and wraps
     # the result as MCP's dual content/structuredContent output (see §5).
     class Dispatcher
-      def initialize(adapter:, registry: CapabilityRegistry.default)
+      def initialize(adapter:, registry: CapabilityRegistry.default, logger: Portage::Ucp.configuration.logger)
         @adapter = adapter
         @registry = registry
+        @logger = logger
       end
 
-      def call(capability:, action:, arguments: {})
+      # @param correlation_id [String, nil] threaded through to the adapter
+      #   (via Support::CheckoutState.with_observability, scoped to this call
+      #   only) so a checkout_state_transition event (§12) it emits during
+      #   this call carries the same id as the tool_called event that
+      #   triggered it. Optional, not correlation_id: required, since
+      #   Dispatcher.call is also the conformance kit's
+      #   (lib/portage/ucp/rspec.rb) and specs' direct entry point, outside
+      #   any MCP request (§23).
+      def call(capability:, action:, arguments: {}, correlation_id: nil)
         capability_definition = @registry.find(capability)
         raise UnknownCapabilityError, capability if capability_definition.nil?
 
@@ -20,12 +29,22 @@ module Portage
 
         Portage::Ucp::PaymentTokenGuard.validate!(arguments[:payment_token]) if arguments.key?(:payment_token)
 
-        result = @adapter.public_send(method_name, **arguments)
+        result = call_adapter(method_name, arguments, correlation_id)
         wrap(capability, result)
       end
 
       private
 
+      def call_adapter(method_name, arguments, correlation_id)
+        unless @adapter.is_a?(Portage::Ucp::Support::CheckoutState)
+          return @adapter.public_send(method_name, **arguments)
+        end
+
+        Portage::Ucp::Support::CheckoutState.with_observability(@adapter, @logger, correlation_id) do
+          @adapter.public_send(method_name, **arguments)
+        end
+      end
+
       def wrap(capability_name, result)
         unless result.respond_to?(:to_wire_h)
           return { content: [{ type: "text", text: result.inspect }], structuredContent: result }

data/lib/portage/ucp/mcp/server.rb

@@ -1,4 +1,5 @@
 require "mcp"
+require "securerandom"
 
 module Portage
   module Ucp
@@ -16,8 +17,10 @@ module Portage
                        authenticator: Portage::Ucp.configuration.authenticator,
                        rate_limiter: Portage::Ucp.configuration.rate_limiter,
                        logger: Portage::Ucp.configuration.logger, **server_opts)
-          context = Context.new(dispatcher: Portage::Ucp::Dispatcher.new(adapter: adapter, registry: registry),
-                                authenticator: authenticator, rate_limiter: rate_limiter, logger: logger)
+          context = Context.new(
+            dispatcher: Portage::Ucp::Dispatcher.new(adapter: adapter, registry: registry, logger: logger),
+            authenticator: authenticator, rate_limiter: rate_limiter, logger: logger
+          )
           tools = registry.advertised(adapter).flat_map do |capability|
             capability.actions.map do |action_name, method_name|
               build_tool(adapter: adapter, capability: capability, action_name: action_name,
@@ -46,17 +49,48 @@ module Portage
 
         def self.call_tool(context:, capability:, action_name:, mutating:, kwargs:)
           server_context = kwargs.delete(:server_context)
-          Portage::Ucp::Observability.log(context.logger, "tool_called", capability: capability.name,
-                                                                         action: action_name, arguments: kwargs)
+          correlation_id = correlation_id_for(server_context)
+          Portage::Ucp::Observability.log(context.logger, "tool_call_received", capability: capability.name,
+                                                                                action: action_name,
+                                                                                correlation_id: correlation_id)
 
           rejection = authorize(context.authenticator, server_context, mutating: mutating) ||
                       rate_limit(context.rate_limiter, server_context, capability.name, mutating: mutating)
           return rejection if rejection
 
-          result = context.dispatcher.call(capability: capability.name, action: action_name, arguments: kwargs)
+          Portage::Ucp::Observability.log(context.logger, "tool_called", capability: capability.name,
+                                                                         action: action_name, arguments: kwargs,
+                                                                         correlation_id: correlation_id)
+
+          result = context.dispatcher.call(capability: capability.name, action: action_name, arguments: kwargs,
+                                           correlation_id: correlation_id)
           ::MCP::Tool::Response.new(result[:content], structured_content: result[:structuredContent])
         end
 
+        # Per-request correlation only (§23): `Context` above is built once per
+        # process in `.build`, and mcp 0.25.0's Streamable HTTP transport is
+        # explicitly stateful/multi-session, so memoizing an id there would
+        # stamp every session in the process with the same value. Prefers the
+        # inbound W3C `traceparent` the MCP spec passes through `_meta`
+        # untouched (SEP-414, see `MCP::TraceContext`) so a caller that already
+        # traces its own calls gets one trace across both sides; generates a
+        # fallback only when absent.
+        #
+        # `traceparent` is unauthenticated input — reachable before
+        # `authorize`/`rate_limit` run, same as the pre-auth event this
+        # correlation id feeds. Validated against W3C Trace Context's own
+        # format before use, which is spec-correct behavior (a malformed
+        # traceparent MUST be treated as absent, restarting the trace), and
+        # incidentally closes off unbounded-length log writes and non-String
+        # values reaching Dispatcher/CheckoutState as a "correlation_id".
+        TRACEPARENT_FORMAT = /\A[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}\z/
+
+        def self.correlation_id_for(server_context)
+          meta = server_context[:_meta] if server_context.respond_to?(:[])
+          traceparent = meta && (meta[:traceparent] || meta["traceparent"])
+          traceparent.is_a?(String) && TRACEPARENT_FORMAT.match?(traceparent) ? traceparent : SecureRandom.uuid
+        end
+
         def self.authorize(authenticator, server_context, mutating:)
           return unless mutating
 

data/lib/portage/ucp/observability.rb

@@ -6,10 +6,19 @@ module Portage
     # Structured log events (§12), emitted through a consumer-injected logger
     # (defaults to Logger.new($stdout)) so the gem instruments nothing to a
     # specific APM — it just exposes the events. Redacts payment_token,
-    # oauth_token, and Authorization by default so a debugging trail never
-    # leaks the exact values this gem is most careful never to log.
+    # oauth_token, and Authorization by default, plus the PII fields that
+    # actually appear on Portage::Ucp::Identity (email) and
+    # Portage::Ucp::PostalAddress (name/address/contact) — §23 step 4
+    # resolving §12's "Money-adjacent PII" phrase, which named no real key:
+    # Money/Total carry amounts and currency only, no PII; the PII that
+    # flows through the gem is on identity-linking results and fulfillment
+    # destinations instead.
     module Observability
-      REDACTED_KEYS = %w[payment_token oauth_token authorization].freeze
+      REDACTED_KEYS = %w[
+        payment_token oauth_token authorization
+        email first_name last_name phone_number
+        street_address extended_address address_locality address_region address_country postal_code
+      ].freeze
       REDACTED = "[REDACTED]".freeze
 
       def self.log(logger, event, **fields)

data/lib/portage/ucp/rack/webhook_endpoint.rb

@@ -11,11 +11,22 @@ module Portage
       # authenticated it. Normalizes to a Portage::Ucp::Order and hands off to a
       # consumer-supplied `on_order_event` callback — the gem doesn't assume
       # anything about how the consumer stores or reacts to order events.
+      #
+      # Emits Observability events (§12) directly via `logger:` rather than a
+      # new config.event_sink seam (§23 step 5): this endpoint is a plain Rack
+      # app, not built through Mcp::Server.build, so it never runs inside an
+      # MCP request and `mcp`'s own around_request/instrumentation_callback
+      # hooks can't see it — the same reason CheckoutState (§23 step 3) needed
+      # a logger threaded to it, not a reason to invent a second config
+      # option: `logger:` already exists on Portage::Ucp.configuration and
+      # every other collaborator that logs takes it the same way.
       class WebhookEndpoint
-        def initialize(secret:, on_order_event:, signature_header: "HTTP_X_UCP_SIGNATURE")
+        def initialize(secret:, on_order_event:, signature_header: "HTTP_X_UCP_SIGNATURE",
+                       logger: Portage::Ucp.configuration.logger)
           @secret = secret
           @on_order_event = on_order_event
           @signature_header = signature_header
+          @logger = logger
         end
 
         def call(env)
@@ -23,7 +34,10 @@ module Portage
           return respond(404, error: "not_found") unless request.post?
 
           body = request.body.read
-          return respond(401, error: "invalid_signature") unless valid_signature?(body, env[@signature_header])
+          unless valid_signature?(body, env[@signature_header])
+            Portage::Ucp::Observability.log(@logger, "order_webhook_rejected", reason: "invalid_signature")
+            return respond(401, error: "invalid_signature")
+          end
 
           handle_order_event(body)
         end
@@ -32,9 +46,13 @@ module Portage
 
         def handle_order_event(body)
           payload = JSON.parse(body, symbolize_names: true)
-          @on_order_event.call(Portage::Ucp::Order.new(**payload))
+          order = Portage::Ucp::Order.new(**payload)
+          Portage::Ucp::Observability.log(@logger, "order_webhook_received", order_id: order.id,
+                                                                             checkout_id: order.checkout_id)
+          @on_order_event.call(order)
           respond(200, ok: true)
         rescue JSON::ParserError, ArgumentError
+          Portage::Ucp::Observability.log(@logger, "order_webhook_rejected", reason: "bad_request")
           respond(400, error: "bad_request")
         end
 

data/lib/portage/ucp/reference_adapter.rb

@@ -145,6 +145,21 @@ module Portage
         end
       end
 
+      # Not memoized against @carts' own id sequence namespace collision:
+      # next_id("cart") is shared with create_cart/update_cart, same as every
+      # other *_id prefix here.
+      def reorder(order_id:, idempotency_key:)
+        dedup(idempotency_key) do
+          order = @orders[order_id]
+          next nil unless order
+
+          available, unavailable = partition_reorderable(order.line_items)
+          cart = build_cart(next_id("cart"), available, nil)
+          @carts[cart.id] = cart
+          Portage::Ucp::ReorderResult.new(cart: cart, unavailable_items: unavailable)
+        end
+      end
+
       def discount_codes_supported? = true
       def fulfillment_supported? = true
 
@@ -266,6 +281,42 @@ module Portage
         [Portage::Ucp::Total.new(type: "subtotal", amount: 0), Portage::Ucp::Total.new(type: "total", amount: 0)]
       end
 
+      # order.line_items here are the checkout's own response-shaped LineItem
+      # objects (see #store_order) — item.id is a variant id, not the
+      # product id build_cart's request-shaped hashes need (build_line_items'
+      # note), so this re-derives product_id by scanning @products the same
+      # way a real adapter would hit its platform's variant lookup.
+      def partition_reorderable(line_items)
+        available = []
+        unavailable = []
+
+        line_items.each do |line_item|
+          product_id = product_id_for_variant(line_item.item.id)
+
+          if product_id.nil?
+            unavailable << unavailable_reorder_item(line_item, "discontinued")
+          elsif line_item.item.id.start_with?(OUT_OF_STOCK_PREFIX)
+            unavailable << unavailable_reorder_item(line_item, "out_of_stock")
+          else
+            available << { product_id: product_id, quantity: line_item.quantity }
+          end
+        end
+
+        [available, unavailable]
+      end
+
+      def unavailable_reorder_item(line_item, reason)
+        Portage::Ucp::UnavailableReorderItem.new(item_id: line_item.item.id, title: line_item.item.title,
+                                                 reason: reason)
+      end
+
+      def product_id_for_variant(variant_id)
+        @products.each_value do |product|
+          return product.id if product.variants.any? { |variant| variant.id == variant_id }
+        end
+        nil
+      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?

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

@@ -16,6 +16,37 @@ module Portage
       # respectively): a checkout this process didn't create is still
       # schema-valid to report, just not information-complete.
       module CheckoutState
+        # Dispatcher wraps each adapter call in .with_observability rather
+        # than writing [logger, correlation_id] onto an instance variable on
+        # the adapter. The adapter instance is shared across every session in
+        # the process (built once in Mcp::Server.build), so an instance
+        # variable is a race: two concurrent requests against the same
+        # adapter clobber each other's correlation id, and
+        # checkout_state_transition ends up stamped with the wrong request's
+        # id — the same per-process-state trap §23 diagnosed for the
+        # correlation id generator itself, one layer down. Storage is
+        # Thread.current, keyed by the adapter's object_id so multiple
+        # adapters (e.g. in specs) don't share a slot, and .with_observability
+        # restores whatever was there before on the way out so a stale value
+        # never leaks into an unrelated direct adapter call afterward.
+        #
+        # A `correlation_id:` kwarg on every checkout method would carry the
+        # same information, but those methods are the public Adapter
+        # contract (§9), and adding a required kwarg there breaks any
+        # existing adapter/caller (§23) — this stays out of that contract.
+        def self.with_observability(adapter, logger, correlation_id)
+          key = observability_key(adapter)
+          previous = Thread.current[key]
+          Thread.current[key] = [logger, correlation_id]
+          yield
+        ensure
+          Thread.current[key] = previous
+        end
+
+        def self.observability_key(adapter)
+          :"portage_ucp_checkout_state_observability_#{adapter.object_id}"
+        end
+
         private
 
         def checkout_status(checkout_id)
@@ -24,6 +55,16 @@ module Portage
 
         def record_checkout_status(checkout_id, status)
           (@checkout_status ||= {})[checkout_id] = status
+          log_checkout_transition(checkout_id, status)
+        end
+
+        def log_checkout_transition(checkout_id, status)
+          logger, correlation_id = Thread.current[CheckoutState.observability_key(self)]
+          return unless logger
+
+          Portage::Ucp::Observability.log(logger, "checkout_state_transition", checkout_id: checkout_id,
+                                                                               status: status,
+                                                                               correlation_id: correlation_id)
         end
 
         # Keyed by String: adapters are called with an order id straight off

data/lib/portage/ucp/value_objects.rb

@@ -521,6 +521,28 @@ module Portage
       end
     end
 
+    # Portage extension (see Adapter#reorder / Capabilities::REORDER) — no
+    # schemas/ counterpart to cite, since it isn't part of the UCP spec.
+    # `reason` is a short adapter-chosen string (e.g. "out_of_stock",
+    # "discontinued"), not a closed enum — same posture as Adapter#cancel_order's
+    # `reason:`.
+    UnavailableReorderItem = Data.define(:item_id, :title, :reason) do
+      def to_wire_h = { "item_id" => item_id, "title" => title, "reason" => reason }
+    end
+
+    # Portage extension — the hydrated Cart plus what got dropped along the
+    # way, so a caller can tell the buyer what to expect before checkout
+    # rather than silently under-filling the cart.
+    ReorderResult = Data.define(:cart, :unavailable_items) do
+      def initialize(cart:, unavailable_items: []) = super
+
+      def to_wire_h
+        h = { "cart" => cart.to_wire_h }
+        h["unavailable_items"] = unavailable_items.map(&:to_wire_h) unless unavailable_items.empty?
+        h
+      end
+    end
+
     Identity = Data.define(:subject, :email, :linked_at)
   end
 end

data/lib/portage/ucp/version.rb

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

data/lib/portage/ucp.rb

@@ -31,6 +31,7 @@ require_relative "ucp/capabilities/catalog"
 require_relative "ucp/capabilities/cart"
 require_relative "ucp/capabilities/checkout"
 require_relative "ucp/capabilities/order"
+require_relative "ucp/capabilities/reorder"
 require_relative "ucp/capabilities/discount"
 require_relative "ucp/capabilities/fulfillment"
 require_relative "ucp/capabilities/identity_linking"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tom Whitbread
@@ -156,6 +156,7 @@ files:
 - lib/portage/ucp/capabilities/fulfillment.rb
 - lib/portage/ucp/capabilities/identity_linking.rb
 - lib/portage/ucp/capabilities/order.rb
+- lib/portage/ucp/capabilities/reorder.rb
 - lib/portage/ucp/capability.rb
 - lib/portage/ucp/capability_negotiator.rb
 - lib/portage/ucp/capability_registry.rb