portage-ucp 0.14.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a245e863596f643972f10c9be20792055d6bf1d2925b90373571966896ee429a
-  data.tar.gz: ad0008e190d5c865e613b616653a7d5dbd5f6b19166f8f71723e57ae70ef7ce0
+  metadata.gz: f99f8f55e4bbfeb276c93c8f1c7e63d36b3f30661702303d1295103e2ea4993c
+  data.tar.gz: 1c21857f2b52165c30994ba40bab0d8522520bfe8d7bb50b7459898630b71647
 SHA512:
-  metadata.gz: d9a93b39705265b1095da290e5615ddbfcf3d3ea529d9b5863308ad99819c70b11ed77bc9805444a003b78c61bb418d4faa756617148d74b964b88beb90b5330
-  data.tar.gz: c2c95f6b3217ea2c2dc6b86318eaa845677b45c753b707ad2eb17f2ae7599f92fe457f7f82a34d46cfea26f1b5bfa8bc17ff4ee46459c94967c6de5ed6286611
+  metadata.gz: c406f740bebf4a83c4eb9184d62e6abc693478ba97b0ab51cd4549bcc8996addd658b84f437f488ffffafa03782be6b2ea464b05057545091380b86b02066f7a
+  data.tar.gz: 6acd7187aad41ebae15d667ebc150e6896e1f0f72b2f86211d173bd77a25a26d1cc0119d7a9375329c688d13423a655244c43b04537a30aa9a3c851c12c4efca

data/CHANGELOG.md

@@ -6,6 +6,19 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+- **Added: `dev.ucp.shopping.permalink` capability** (UCP 2026-08-25). An adapter that overrides `Adapter#permalink_endpoint` (default `nil`) to return its https browser endpoint is advertised with `config.endpoint`. `Capability` takes an optional `config:` callable for the manifest entry's `config`. No MCP tool: the permalink is a browser redirect the host serves (design-log §61).
+- **Added: policy disclosure warnings on `Cart` and `Checkout`** (UCP 2026-08-25). Each entry of `policies:` now also yields a `messages[]` warning with `code` equal to the policy `type`, `presentation: "disclosure"`, `content` from the description and `url`/`path` when the policy has them. Derived in `to_wire_h`, so every adapter gets it and nothing is stored. Orders are unchanged (design-log §62).
+- **Added: optional `messages:` on `Cart` and `Checkout`.** An array of wire-shaped message hashes (default `[]`) an adapter can set itself. `to_wire_h` emits them before the derived policy warnings and drops a derived warning when the adapter already warned with the same `code`. `messages` is omitted from the wire when the combined list is empty (design-log §63).
+- **Added: post-purchase adjustments on the order ledger** (order-ledger plan Phase 3). `Dispatcher` writes the `adjustments` of the `Order` returned by `cancel_order`, `refund_order` or `request_return` onto that order's existing ledger record; line items, totals and other purchase facts are never rewritten. `OrderLedger#refresh(order_id, adapter:)` re-fetches with `get_order` and replaces the stored adjustments the same way, for disputes and returns that settle later. `OrderLedger#unresolved` lists every `pending` adjustment with its order id. An order with no snapshot is skipped, not backfilled. A ledger write failure raises only after the adapter call has succeeded, as the Phase 1 snapshot does (design-log §64).
+
+## [0.15.1] - 2026-10-18
+
+- **Fixed: generated MCP tools carry a real description, per-parameter description, and `readOnlyHint`/`destructiveHint`/`idempotentHint` annotations**, instead of `Mcp::Server.build_tool` emitting the bare `capability#action` identifier as the description and an empty schema for every parameter. New `Mcp::ToolMetadata` supplies this per action, sourced from the `@param`/`@return` docs already on `Adapter`'s methods; an action without an entry still falls back to the old `capability#action` format. `Adapter`, the wire format and every adapter gem are unchanged — this only changes what a calling agent reads in `tools/list`. Patch-level.
+
+## [0.15.0] - 2026-10-13
+
+- **Added: optional `policies:` on `Cart`, `Checkout`, `Order`, `Product`, `CatalogSearchResult` and `ProductDetail`** (UCP 2026-08-25 `policies[]`). An array of `policy.json` hashes (`type` and `description` required; `applies_to` and `url` optional), default `[]`, omitted from the wire payload when empty. `portage-ucp-shopify` 0.7.0 supplies it (design-log §60).
+
 ## [0.14.0] - 2026-10-09
 
 Moves the gem to UCP 2026-08-25 (design-log §56-58). Minor-level for a pre-1.0 gem, with breaking config changes below.

data/lib/portage/ucp/adapter.rb

@@ -105,7 +105,7 @@ module Portage
 
       # --- 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) ---
+      # of the 2026-08-25 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
@@ -132,6 +132,16 @@ module Portage
       # @return [Boolean]
       def fulfillment_supported? = false
 
+      # --- Permalink (dev.ucp.shopping.permalink) ---
+      # The business's browser endpoint for shopping permalinks, e.g.
+      # "https://merchant.example/buy" (absolute https, no query, fragment or
+      # trailing slash). The endpoint itself is a redirect route the
+      # business's storefront serves, not an MCP action, so this is a
+      # config-carrying predicate: nil (the default) leaves the capability
+      # out, a String advertises it with `config.endpoint`.
+      # @return [String, nil]
+      def permalink_endpoint = nil
+
       # --- Identity Linking (dev.ucp.shopping.identity, OAuth 2.0) ---
       # @return [Portage::Ucp::Identity] linked profile for an exchanged OAuth token
       def link_identity(oauth_token:) = not_implemented

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

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

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

@@ -0,0 +1,19 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # schemas/shopping/permalink.json — a browser redirect endpoint the
+      # business serves (services/shopping/permalink.openapi.json), not an
+      # MCP action, so `actions` is empty and advertisement runs off
+      # Adapter#permalink_endpoint, whose value is the required
+      # `config.endpoint`.
+      PERMALINK = Portage::Ucp::Capability.new(
+        name: "dev.ucp.shopping.permalink",
+        version: "1",
+        schema: "shopping/permalink.json",
+        actions: {},
+        predicate: :permalink_endpoint,
+        config: ->(adapter) { { endpoint: adapter.permalink_endpoint } }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capability.rb

@@ -15,7 +15,11 @@ module Portage
       # `schema:` is the capability's schema path under a UCP revision's
       # `schemas/` (e.g. "shopping/checkout.json"); the manifest turns it into
       # the `schema` URL 2026-08-25 business profiles require.
-      def initialize(name:, version:, actions:, predicate: nil, schema: nil)
+      #
+      # `config:` is a callable taking the adapter and returning the `config`
+      # object the manifest entry carries (permalink's `{endpoint:}`).
+      def initialize(name:, version:, actions:, predicate: nil, schema: nil, config: nil)
+        @config = config
         @name = name
         @schema = schema
         @version = version
@@ -32,6 +36,9 @@ module Portage
         actions.values.any? { |method_name| overridden?(adapter, method_name) }
       end
 
+      # @return [Hash, nil] the manifest entry's `config`, if the capability has one
+      def config_for(adapter) = @config&.call(adapter)
+
       private
 
       def overridden?(adapter, method_name)

data/lib/portage/ucp/dispatcher.rb

@@ -9,6 +9,10 @@ module Portage
       # the only `dev.ucp.shopping.checkout` action that dispatches a charge.
       PAYMENT_COMPLETING_ACTION = "complete_checkout".freeze
 
+      # Each returns the updated Order whose adjustments land on the order
+      # ledger (docs/plans/order-ledger.md Phase 3).
+      ORDER_ADJUSTING_ACTIONS = %w[cancel_order refund_order request_return].freeze
+
       # @param shop [String, nil] identifies which store this Dispatcher
       #   instance is completing charges for, threaded straight onto the
       #   transaction log record — Dispatcher/Adapter have no shared notion
@@ -92,6 +96,11 @@ module Portage
                  else
                    call_adapter(method_name, arguments, correlation_id)
                  end
+        # Same after-the-adapter posture as the Phase 1 snapshot in
+        # #call_and_log_transaction: the cancel/refund/return has already
+        # happened upstream, so a ledger write failure surfaces only after
+        # it — never instead of it, never retried or rolled back here.
+        @order_ledger.record_adjustments(result) if result && ORDER_ADJUSTING_ACTIONS.include?(action)
         validate_outbound_boundaries!(result)
         wrap(capability, result)
       end

data/lib/portage/ucp/manifest.rb

@@ -62,6 +62,8 @@ module Portage
         @registry.advertised(@adapter).to_h do |capability|
           entry = { version: UCP_VERSION }
           entry[:schema] = "https://ucp.dev/#{UCP_VERSION}/schemas/#{capability.schema}" if capability.schema
+          config = capability.config_for(@adapter)
+          entry[:config] = config if config
           [capability.name, [entry]]
         end
       end

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

@@ -42,19 +42,40 @@ module Portage
         def self.build_tool(adapter:, capability:, action_name:, method_name:, context:)
           keyword_params = adapter.method(method_name).parameters.select { |type, _| %i[key keyreq].include?(type) }
           required = keyword_params.select { |type, _| type == :keyreq }.map { |_, name| name.to_s }
-          properties = keyword_params.to_h { |_, name| [name.to_s, {}] }
+          metadata = ToolMetadata::TOOLS[action_name]
+          properties = keyword_params.to_h { |_, name| [name.to_s, property_schema(name.to_s, metadata)] }
           mutating = keyword_params.any? { |_, name| name == :idempotency_key }
 
           ::MCP::Tool.define(
             name: action_name,
-            description: "#{capability.name}##{action_name}",
-            input_schema: { type: "object", properties: properties, required: required }
+            description: description_for(capability, action_name, metadata),
+            input_schema: { type: "object", properties: properties, required: required },
+            annotations: metadata && metadata[:annotations]
           ) do |**kwargs|
             Portage::Ucp::Mcp::Server.call_tool(context: context, capability: capability, action_name: action_name,
                                                 mutating: mutating, kwargs: kwargs)
           end
         end
 
+        # @return [String] the documented description from ToolMetadata, or
+        #   (for an undocumented/extension action) the old namespaced
+        #   fallback, e.g. "dev.ucp.shopping.catalog#get_product".
+        def self.description_for(capability, action_name, metadata)
+          metadata ? metadata[:description] : "#{capability.name}##{action_name}"
+        end
+
+        # @return [Hash] a property's JSON Schema entry: a description from
+        #   ToolMetadata when the action has an entry (none for an
+        #   undocumented/extension action — see `metadata&.fetch` above), plus
+        #   a `type` where ToolMetadata::PARAM_TYPES pins one down for this
+        #   param name.
+        def self.property_schema(name, metadata)
+          schema = {}
+          schema[:description] = metadata[:params][name] if metadata && metadata[:params][name]
+          schema[:type] = ToolMetadata::PARAM_TYPES[name] if ToolMetadata::PARAM_TYPES[name]
+          schema
+        end
+
         def self.call_tool(context:, capability:, action_name:, mutating:, kwargs:)
           server_context = kwargs.delete(:server_context)
           correlation_id = correlation_id_for(server_context)

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

@@ -0,0 +1,189 @@
+module Portage
+  module Ucp
+    module Mcp
+      # Per-action tool metadata — description, parameter descriptions, and
+      # MCP annotations — for Server.build_tool to attach to each generated
+      # ::MCP::Tool. Kept separate from Capability (name/version/actions/
+      # schema — the UCP wire contract) since this is MCP-presentation only:
+      # what a calling agent reads before it decides whether and how to call
+      # a tool, not part of the UCP spec itself. Content mirrors the @param/
+      # @return docs already on Adapter's methods (adapter.rb) rather than
+      # inventing anything new.
+      module ToolMetadata
+        ID = "A stable identifier returned by an earlier call (e.g. get_cart, create_checkout) " \
+             "— not something the caller makes up.".freeze
+        IDEMPOTENCY_KEY = "Caller-generated key that dedupes retries: calling again with the same " \
+                          "key returns the original result instead of repeating the effect.".freeze
+        REPLACE_NOTE = "Replaces the existing contents rather than adding to them — resend the " \
+                       "full desired list with an item adjusted, added, or omitted.".freeze
+
+        # JSON Schema `type` for parameter names whose shape is unambiguous
+        # from the name alone and constant across every action it appears
+        # in; left out entirely (no `type`) where it genuinely varies.
+        PARAM_TYPES = {
+          "query" => "string", "limit" => "integer", "product_id" => "string",
+          "product_ids" => "array", "cart_id" => "string", "checkout_id" => "string",
+          "order_id" => "string", "idempotency_key" => "string", "payment_token" => "string",
+          "reason" => "string", "line_items" => "array", "discount_codes" => "array",
+          "fulfillment" => "object", "mandate" => "object"
+        }.freeze
+
+        TOOLS = {
+          "search_catalog" => {
+            description: "Search the store's product catalog by free-text query, returning up to " \
+                         "`limit` matches with price and availability. Use this to discover products " \
+                         "when you don't yet have an ID; once you do, use get_product for one or " \
+                         "lookup_catalog for several — neither re-runs a search.",
+            params: { "query" => "Free-text search query.", "limit" => "Maximum number of results to return." },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "get_product" => {
+            description: "Fetch full details — price, availability, and whatever else the store's " \
+                         "catalog carries — for one product by ID. Returns not-found rather than " \
+                         "raising if the ID doesn't exist. Use search_catalog first if you don't " \
+                         "already have the ID; use lookup_catalog instead for several known IDs, to " \
+                         "avoid one call per product.",
+            params: { "product_id" => "Product ID, as returned by search_catalog or lookup_catalog." },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "lookup_catalog" => {
+            description: "Batch-fetch several products by ID in one call, same result shape as " \
+                         "search_catalog. Use when you already have a set of product IDs — e.g. " \
+                         "hydrating a cart or order — instead of calling get_product once per ID.",
+            params: { "product_ids" => "Product IDs to fetch, as returned by search_catalog, a cart, or an order." },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "create_cart" => {
+            description: "Start a new cart from a list of line items — the cart's complete starting " \
+                         "contents, not an item appended to an existing one. Use update_cart to change " \
+                         "a cart that already exists. Optional discount_codes applies coupons if the " \
+                         "store supports them.",
+            params: {
+              "line_items" => "Items to add, each {product_id:, quantity:}.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Discount/coupon codes to apply, if the store supports them."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "get_cart" => {
+            description: "Fetch a cart's current contents and totals by ID.",
+            params: { "cart_id" => ID },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "update_cart" => {
+            description: "Replace a cart's contents. #{REPLACE_NOTE} Use this for every change to an " \
+                         "existing cart: adding an item, removing one, or changing a quantity.",
+            params: {
+              "cart_id" => ID,
+              "line_items" => "The cart's complete desired contents, each {product_id:, quantity:}. #{REPLACE_NOTE}",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Discount/coupon codes to apply, if the store supports them."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "cancel_cart" => {
+            description: "Cancel and discard a cart. Irreversible — use this to abandon a cart the " \
+                         "shopper no longer wants.",
+            params: { "cart_id" => ID, "idempotency_key" => IDEMPOTENCY_KEY },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "create_checkout" => {
+            description: "Start a checkout directly from line items, skipping a separate cart. " \
+                         "Optional discount_codes applies coupons; optional fulfillment carries the " \
+                         "shopper's desired shipping or pickup selection, if the store supports it. " \
+                         "Does not charge anything — call complete_checkout once the shopper approves " \
+                         "the total from get_checkout.",
+            params: {
+              "line_items" => "Items to buy, each {product_id:, quantity:}.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Discount/coupon codes to apply, if the store supports them.",
+              "fulfillment" => "Desired shipping/pickup method selection, if the store supports it."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "get_checkout" => {
+            description: "Fetch a checkout's current contents, totals, and status by ID.",
+            params: { "checkout_id" => ID },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "update_checkout" => {
+            description: "Replace a checkout's contents before payment. #{REPLACE_NOTE} Also accepts " \
+                         "updated discount_codes or fulfillment selection. Does not charge anything.",
+            params: {
+              "checkout_id" => ID,
+              "line_items" => "The checkout's complete desired contents, each {product_id:, quantity:}. " \
+                              "#{REPLACE_NOTE}",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Discount/coupon codes to apply, if the store supports them.",
+              "fulfillment" => "Desired shipping/pickup method selection, if the store supports it."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "complete_checkout" => {
+            description: "Charge the checkout and place the order — the one tool here that moves " \
+                         "money. Takes a single-use payment_token from a payment handler, never a raw " \
+                         "card number. Re-checks stock at this point, since catalog calls don't " \
+                         "guarantee live inventory, and fails rather than charging if a line item is " \
+                         "no longer available. Only call this after the shopper has explicitly " \
+                         "approved the exact total from get_checkout.",
+            params: {
+              "checkout_id" => ID,
+              "payment_token" => "Single-use payment token from a payment handler — never a raw card number.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "mandate" => "Optional AP2 payment mandate authorizing this charge, alongside or instead " \
+                           "of payment_token."
+            },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "cancel_checkout" => {
+            description: "Cancel a checkout before payment. Irreversible — use this to abandon a " \
+                         "checkout the shopper no longer wants. Safe with respect to money, since " \
+                         "complete_checkout hasn't run yet.",
+            params: { "checkout_id" => ID, "idempotency_key" => IDEMPOTENCY_KEY },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "get_order" => {
+            description: "Fetch a placed order's status, line items, and totals by ID. Returns " \
+                         "not-found rather than raising if the ID doesn't exist.",
+            params: { "order_id" => ID },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "cancel_order" => {
+            description: "Cancel an already-placed order. Irreversible. Optional reason is a " \
+                         "free-text note for the merchant, not a fixed enum.",
+            params: {
+              "order_id" => ID, "idempotency_key" => IDEMPOTENCY_KEY,
+              "reason" => "Optional free-text reason for the cancellation."
+            },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "request_return" => {
+            description: "Request a return for one or more order line items. This files the request; " \
+                         "it doesn't refund money itself — the order shows the items as pending until " \
+                         "the merchant processes it. Use refund_order only once a refund has actually " \
+                         "been approved.",
+            params: {
+              "order_id" => ID,
+              "line_items" => "Items to return, each {id:, quantity:}.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "reason" => "Optional free-text reason for the return."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "refund_order" => {
+            description: "Refund one or more order line items, moving money back to the shopper. " \
+                         "Irreversible. Use request_return first if the merchant requires a return " \
+                         "before refunding.",
+            params: {
+              "order_id" => ID,
+              "line_items" => "Items to refund, each {id:, quantity:}.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "reason" => "Optional free-text reason for the refund."
+            },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          }
+        }.freeze
+      end
+    end
+  end
+end

data/lib/portage/ucp/security/signature.rb

@@ -7,7 +7,7 @@ module Portage
     module Security
       # Verifies that an inbound agent request carries a valid RFC 9421 HTTP
       # Message Signature, per UCP's own signature spec
-      # (ucp.dev/2026-04-08/specification/signatures/, pinned 2026-09-15 —
+      # (ucp.dev/2026-08-25/specification/signatures/, pinned 2026-09-15 —
       # this is the piece §22 of the design log flagged as unresearched
       # before writing code, now checked against the live spec rather than
       # guessed). This is a distinct concern from three other signing

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

@@ -38,6 +38,51 @@ module Portage
           @store.record(order.id, record)
         end
 
+        # Phase 3: replaces the stored snapshot's `adjustments` with
+        # `order.adjustments` — the upstream list is authoritative for
+        # adjustment state (a `pending` return settles on the merchant's
+        # clock), so a merge would only keep stale statuses. Every other
+        # purchase fact stays exactly as first recorded; `order`'s own
+        # line items/totals are never read.
+        #
+        # No-op (returns nil) when there's no purchase snapshot for the
+        # order: Phase 2's "report the gap, don't backfill" rule — a
+        # post-purchase payload isn't evidence of what was originally paid.
+        #
+        # ponytail: find-then-record isn't one lock; a write landing in
+        # between is lost. Add a Store#update if two writers ever share an
+        # order id concurrently.
+        def record_adjustments(order)
+          existing = find(order.id)
+          return nil unless existing
+
+          # Same omit-when-empty shape as Order#to_wire_h.
+          adjustments = order.adjustments.map(&:to_wire_h)
+          snapshot = existing["order"].except("adjustments")
+          snapshot = existing["order"].merge("adjustments" => adjustments) unless adjustments.empty?
+          @store.record(order.id, existing.merge("order" => snapshot))
+        end
+
+        # Explicit reconcile for adjustments with no originating dispatch
+        # (disputes) or that settle later (returns) — re-fetches via the
+        # caller's `adapter` and merges adjustments only, per
+        # #record_adjustments. No polling (plan Phase 3): call it when you
+        # want current state.
+        def refresh(order_id, adapter:)
+          order = adapter.get_order(order_id: order_id)
+          record_adjustments(order) if order
+        end
+
+        # Adjustments still `pending` — money owed but not yet received —
+        # each paired with its order id.
+        def unresolved
+          all.flat_map do |record|
+            order = record["order"]
+            Array(order["adjustments"]).select { |adjustment| adjustment["status"] == "pending" }
+                                       .map { |adjustment| { "order_id" => order["id"], "adjustment" => adjustment } }
+          end
+        end
+
         def find(order_id)
           @store.find(order_id)
         end

data/lib/portage/ucp/value_objects.rb

@@ -1,3 +1,5 @@
+require "cgi"
+
 module Portage
   module Ucp
     # Internal arithmetic helper only — never appears in a wire shape directly.
@@ -115,9 +117,10 @@ module Portage
     # (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
+                          :list_price_range, :media, :options, :tags, :metadata, :rating, :policies) 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)
+                     list_price_range: nil, media: [], options: [], tags: [], metadata: nil, rating: nil,
+                     policies: [])
         super
       end
 
@@ -135,6 +138,7 @@ module Portage
         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["policies"] = policies unless policies.empty?
         h
       end
     end
@@ -144,12 +148,13 @@ module Portage
     # 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
+    CatalogSearchResult = Data.define(:products, :messages, :policies) do
+      def initialize(products:, messages: [], policies: []) = super
 
       def to_wire_h
         h = { "products" => products.map(&:to_wire_h) }
         h["messages"] = messages unless messages.empty?
+        h["policies"] = policies unless policies.empty?
         h
       end
     end
@@ -161,8 +166,14 @@ module Portage
     # 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 }
+    ProductDetail = Data.define(:product, :policies) do
+      def initialize(product:, policies: []) = super
+
+      def to_wire_h
+        h = { "product" => product.to_wire_h }
+        h["policies"] = policies unless policies.empty?
+        h
+      end
     end
 
     # One cost-breakdown entry (schemas/shopping/types/total.json). `amount` is a
@@ -198,6 +209,10 @@ module Portage
       end
     end
 
+    # `policies` (cart/checkout/order/catalog responses and products) is the
+    # 2026-08-25 policy.json array (return/warranty terms), optional and omitted
+    # when empty. Entries stay wire-shaped hashes (`type` and `description` are
+    # required, `applies_to`/`url` optional), same posture as `messages`.
     # schemas/shopping/types/link.json
     Link = Data.define(:type, :url, :title) do
       def initialize(type:, url:, title: nil) = super
@@ -374,19 +389,57 @@ module Portage
       end
     end
 
+    # A policy's buyer-facing disclosure obligation is a `messages[]` warning
+    # whose `code` equals the policy `type` (policy.json). Derived at
+    # serialization for Cart and Checkout, so it needs no storage and survives
+    # any rebuild without duplicating. Content is the plain (else markdown)
+    # description; an html-only policy has its tags stripped, since the
+    # warning schema has no html format.
+    def self.policy_messages(policies)
+      policies.map do |policy|
+        description = policy["description"]
+        markdown = !description["plain"] && description["markdown"]
+        content = description["plain"] || description["markdown"] || html_to_text(description["html"])
+        message = { "type" => "warning", "code" => policy["type"], "presentation" => "disclosure",
+                    "content" => content }
+        message["content_type"] = "markdown" if markdown
+        message["url"] = policy["url"] if policy["url"]
+        message["path"] = policy["applies_to"].first if policy["applies_to"]&.one?
+        message
+      end
+    end
+
+    # Adapter messages first, then the derived policy warnings, minus any
+    # whose `code` the adapter already warned about (that warning meets the
+    # disclosure obligation). Only the adapter's `messages` are stored.
+    def self.wire_messages(messages, policies)
+      warned = messages.select { |m| m["type"] == "warning" }.to_set { |m| m["code"] }
+      messages + policy_messages(policies).reject { |m| warned.include?(m["code"]) }
+    end
+
+    def self.html_to_text(html)
+      text = html.gsub(%r{</(p|div|li|h\d)>|<br\s*/?>}i, "\n").gsub(/<[^>]*>/, "")
+      CGI.unescapeHTML(text).gsub(/\n{3,}/, "\n\n").strip
+    end
+
     # schemas/shopping/cart.json — requires ucp/id/line_items/currency/totals.
     # The "ucp" envelope is added centrally by Portage::Ucp::WireEnvelope, not stored
     # on the value object itself.
     # `discounts` is the dev.ucp.shopping.discount extension (optional on both
     # cart.json and its own schema) — omitted from the wire payload when empty,
     # same as Order#adjustments.
-    Cart = Data.define(:id, :line_items, :currency, :totals, :discounts) do
-      def initialize(id:, line_items:, currency:, totals:, discounts: Discounts.new) = super
+    # `messages` holds only the adapter's own wire-shaped message hashes;
+    # policy warnings are derived in to_wire_h (see Ucp.wire_messages).
+    Cart = Data.define(:id, :line_items, :currency, :totals, :discounts, :policies, :messages) do
+      def initialize(id:, line_items:, currency:, totals:, discounts: Discounts.new, policies: [], messages: []) = super
 
       def to_wire_h
         h = { "id" => id, "line_items" => line_items.map(&:to_wire_h), "currency" => currency,
               "totals" => totals.map(&:to_wire_h) }
         h["discounts"] = discounts.to_wire_h unless discounts.empty?
+        h["policies"] = policies unless policies.empty?
+        all = Ucp.wire_messages(messages, policies)
+        h["messages"] = all unless all.empty?
         h
       end
     end
@@ -415,9 +468,9 @@ module Portage
     # omitted from the wire payload when empty), same posture as
     # Order#adjustments.
     Checkout = Data.define(:id, :status, :line_items, :currency, :totals, :links, :order, :discounts,
-                           :fulfillment) do
+                           :fulfillment, :policies, :messages) do
       def initialize(id:, status:, line_items:, currency:, totals:, links:, order: nil, discounts: Discounts.new,
-                     fulfillment: CheckoutFulfillment.new)
+                     fulfillment: CheckoutFulfillment.new, policies: [], messages: [])
         super
       end
 
@@ -427,6 +480,9 @@ module Portage
         h["order"] = order.to_wire_h if order
         h["discounts"] = discounts.to_wire_h unless discounts.empty?
         h["fulfillment"] = fulfillment.to_wire_h unless fulfillment.empty?
+        h["policies"] = policies unless policies.empty?
+        all = Ucp.wire_messages(messages, policies)
+        h["messages"] = all unless all.empty?
         h
       end
     end
@@ -508,9 +564,9 @@ module Portage
     # line_items/fulfillment/currency/totals. `adjustments` is optional —
     # omitted from the wire payload when empty.
     Order = Data.define(:id, :checkout_id, :permalink_url, :line_items, :fulfillment, :currency, :totals,
-                        :adjustments) do
+                        :adjustments, :policies) do
       def initialize(id:, checkout_id:, permalink_url:, line_items:, fulfillment:, currency:, totals:,
-                     adjustments: [])
+                     adjustments: [], policies: [])
         super
       end
 
@@ -519,6 +575,7 @@ module Portage
               "line_items" => line_items.map(&:to_wire_h), "fulfillment" => fulfillment.to_wire_h,
               "currency" => currency, "totals" => totals.map(&:to_wire_h) }
         h["adjustments"] = adjustments.map(&:to_wire_h) unless adjustments.empty?
+        h["policies"] = policies unless policies.empty?
         h
       end
     end

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.14.0".freeze
+    VERSION = "0.15.1".freeze
   end
 end

data/lib/portage/ucp.rb

@@ -57,12 +57,14 @@ require_relative "ucp/capabilities/order"
 require_relative "ucp/capabilities/reorder"
 require_relative "ucp/capabilities/discount"
 require_relative "ucp/capabilities/fulfillment"
+require_relative "ucp/capabilities/permalink"
 require_relative "ucp/capabilities/payment_enrollment"
 require_relative "ucp/capabilities/payment_method"
 require_relative "ucp/capabilities/shopper_data"
 require_relative "ucp/capabilities/identity_linking"
 require_relative "ucp/capability_registry"
 require_relative "ucp/dispatcher"
+require_relative "ucp/mcp/tool_metadata"
 require_relative "ucp/mcp/server"
 require_relative "ucp/rack/forwarded_request"
 require_relative "ucp/rack/manifest_endpoint"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: json_schemer
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -165,6 +193,7 @@ files:
 - lib/portage/ucp/capabilities/order.rb
 - lib/portage/ucp/capabilities/payment_enrollment.rb
 - lib/portage/ucp/capabilities/payment_method.rb
+- lib/portage/ucp/capabilities/permalink.rb
 - lib/portage/ucp/capabilities/reorder.rb
 - lib/portage/ucp/capabilities/shopper_data.rb
 - lib/portage/ucp/capability.rb
@@ -176,6 +205,7 @@ files:
 - lib/portage/ucp/errors.rb
 - lib/portage/ucp/manifest.rb
 - lib/portage/ucp/mcp/server.rb
+- lib/portage/ucp/mcp/tool_metadata.rb
 - lib/portage/ucp/observability.rb
 - lib/portage/ucp/payment_enrollment_guard.rb
 - lib/portage/ucp/payment_token_guard.rb