portage-ucp 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3030cd7b510d8e0e829878dd48ab11fd18f70e0d0e5cac5107852ead26a0077c
-  data.tar.gz: 7e6abed9cd7ea40da3ee5f8681ec69f80a6f8c852e8956901f4fce1b383816da
+  metadata.gz: 0a7cd8175dc8b1acd3a884205a5df5f030e897bf1090cdf6675fd582f7c4f0ee
+  data.tar.gz: 8acedc01a0e9dff428670248e9257647b26fb7ee54ea1e0625f67bf169c81285
 SHA512:
-  metadata.gz: 4c4dddb8b6aaeaa674d270400287420f3bcbbfc028c8d38b9482fe53fe2cb47b493711cd7fffe50051b892b49f720f4332ba0e3af89fe595df9d46cdf80c5306
-  data.tar.gz: 5b1c1ee5a21fae8d7c8821c43820bcdcca15f54001e9d6e25af3b4916965da69a1bedb144faadb06ec222c11a59d3cd7e60c753579a4d8931924f51e62f06b78
+  metadata.gz: 6422591fbb901e8e901b4ca6b6bba5b3cd8c6e776d1dd3980536c8245598787fbe2b25d4dd193bf5a05ed87cf6c4e2ff0d7f0b93222ae2716631f23fa028b7f6
+  data.tar.gz: 3d5928f821375dc3a71b7f9cae13864430d90b0167aebb8ca35f5ed008fe3e5617e0df0a95ada2f2db2fc962d8309eea7d852453374a81ce046f1609b9a366b7

data/CHANGELOG.md

@@ -6,6 +6,18 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-10-21
+
+- **Changed: MCP tool descriptions rewritten against the TDQS rubric** (tdqs.dev, the score Glama shows). Each tool's description now names its siblings for when and when not to use it, states the auth and rate-limit behavior of state-changing tools, and says what it returns, since tools have no output schema. Parameter descriptions say where IDs come from. `Mcp::Server.build` now sends server `instructions` (`ToolMetadata::INSTRUCTIONS`, overridable with `instructions:`) that walk the catalog → cart → checkout → order flow. `tools/list` text only; tool names, schemas and annotations are unchanged.
+- **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).

data/lib/portage/ucp/adapter.rb

@@ -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

@@ -23,7 +23,8 @@ module Portage
         def self.build(adapter:, registry: Portage::Ucp.configuration.registry,
                        authenticator: Portage::Ucp.configuration.authenticator,
                        rate_limiter: Portage::Ucp.configuration.rate_limiter,
-                       logger: Portage::Ucp.configuration.logger, journal: nil, **server_opts)
+                       logger: Portage::Ucp.configuration.logger, journal: nil,
+                       instructions: ToolMetadata::INSTRUCTIONS, **server_opts)
           context = Context.new(
             dispatcher: Portage::Ucp::Dispatcher.new(adapter: adapter, registry: registry, logger: logger,
                                                      journal: journal),
@@ -36,25 +37,46 @@ module Portage
             end
           end
 
-          ::MCP::Server.new(name: "portage-ucp", tools: tools, **server_opts)
+          ::MCP::Server.new(name: "portage-ucp", tools: tools, instructions: instructions, **server_opts)
         end
 
         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,242 @@
+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. Written against the TDQS
+      # rubric (tdqs.dev): purpose, when/when-not with named siblings,
+      # behavior annotations can't carry, and return shape (no output schema).
+      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
+        AUTH_NOTE = "Requires an authenticated session and may be rate-limited; a rejected call " \
+                    "returns an error result and changes nothing.".freeze
+        OPEN_NOTE = "Needs no authentication and is never rate-limited.".freeze
+
+        INSTRUCTIONS = "Shopping tools for one store, following the UCP lifecycle: catalog → cart → " \
+                       "checkout → order. Find products with search_catalog, read them with " \
+                       "get_product or lookup_catalog. Either build a cart (create_cart/update_cart) " \
+                       "or go straight to create_checkout; a checkout never charges until " \
+                       "complete_checkout, which must only follow the shopper's explicit approval of " \
+                       "the exact total shown by get_checkout. After purchase, use get_order, " \
+                       "cancel_order, request_return and refund_order. Catalog reads are open; every " \
+                       "tool that changes state needs an authenticated session, and a server run " \
+                       "without one is read-only. Payment is a single-use token, never a card number. " \
+                       "Prices and stock come live from the store and can change between calls.".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 and return up to " \
+                         "`limit` matching products, each with ID, title, price range, variants and " \
+                         "availability. Use it to discover products when you have no product ID yet; " \
+                         "once you have IDs, use get_product (one) or lookup_catalog (several) " \
+                         "instead of searching again. #{OPEN_NOTE} An empty product list means no " \
+                         "match, not an error; results reflect the live store and can change between calls.",
+            params: {
+              "query" => "Free-text search, e.g. a product name, brand or category (\"burton snowboard\").",
+              "limit" => "Maximum number of products to return; 5–20 suits most searches."
+            },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "get_product" => {
+            description: "Fetch the full record for one product by ID: title, description, price " \
+                         "range, every variant with its own price and availability, URL and store " \
+                         "policies. Use it when you need variant-level detail for a single product " \
+                         "before adding it to a cart; use lookup_catalog for several IDs at once, and " \
+                         "search_catalog if you don't have an ID. #{OPEN_NOTE} An unknown ID returns " \
+                         "an empty result rather than an error.",
+            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: "Fetch several products by ID in one call, returning the same product list " \
+                         "shape as search_catalog. Use it when you already hold a set of IDs — e.g. to " \
+                         "refresh prices for a cart or order — instead of calling get_product once per " \
+                         "ID; use search_catalog when you have a query rather than IDs. #{OPEN_NOTE} " \
+                         "IDs the store doesn't recognise are omitted from the result, not reported as errors.",
+            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: "Create a new cart holding the given line items and return it with its ID, " \
+                         "line items, currency and totals. Use it to collect items before checkout; " \
+                         "to change a cart that already exists use update_cart, and to buy straight " \
+                         "away without a cart use create_checkout. Nothing is reserved or charged. " \
+                         "#{AUTH_NOTE}",
+            params: {
+              "line_items" => "The cart's starting contents, each {product_id:, quantity:} with a " \
+                              "product or variant ID from the catalog tools.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Optional coupon codes to apply, if the store supports them."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "get_cart" => {
+            description: "Fetch an existing cart by ID and return its line items, currency, applied " \
+                         "discounts and current totals, recalculated against live store prices. Use " \
+                         "it to show the shopper what is in the cart; it is for carts only — use " \
+                         "get_checkout once a checkout exists and get_order after purchase. #{OPEN_NOTE}",
+            params: { "cart_id" => "Cart ID returned by create_cart. #{ID}" },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "update_cart" => {
+            description: "Replace an existing cart's line items and discount codes, then return the " \
+                         "updated cart with new totals. #{REPLACE_NOTE} Use it for every change to a " \
+                         "cart — add, remove or change a quantity; use create_cart only for a new " \
+                         "cart and update_checkout once the shopper has moved to checkout. " \
+                         "Nothing is charged. #{AUTH_NOTE}",
+            params: {
+              "cart_id" => "Cart ID returned by create_cart. #{ID}",
+              "line_items" => "The cart's complete desired contents, each {product_id:, quantity:}.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Optional coupon codes, replacing those applied; leave out to keep the current ones."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "cancel_cart" => {
+            description: "Abandon a cart and return it in its final state; don't reuse the cart ID " \
+                         "afterwards (some stores delete it, others such as Shopify let it expire). " \
+                         "Use it when the shopper gives up on the cart; to just " \
+                         "remove items use update_cart instead, and to abandon a checkout use " \
+                         "cancel_checkout. No money is involved. #{AUTH_NOTE}",
+            params: { "cart_id" => "Cart ID returned by create_cart. #{ID}", "idempotency_key" => IDEMPOTENCY_KEY },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "create_checkout" => {
+            description: "Open a checkout for the given line items and return it with its ID, status, " \
+                         "currency, itemised totals (including tax and shipping once known) and links. " \
+                         "Use it when the shopper is ready to buy; use create_cart instead if they " \
+                         "are still collecting items. Does not charge — complete_checkout does that, " \
+                         "only after the shopper approves the total. #{AUTH_NOTE}",
+            params: {
+              "line_items" => "Items to buy, each {product_id:, quantity:} with a product or variant ID " \
+                              "from the catalog tools or a cart.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Optional coupon codes to apply, if the store supports them.",
+              "fulfillment" => "Optional shipping or pickup selection; leave it out to get the " \
+                               "store's available options back on the checkout."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "get_checkout" => {
+            description: "Fetch an existing checkout by ID and return its status, line items, " \
+                         "currency and itemised totals. Use it to show the shopper the exact final " \
+                         "total to approve before complete_checkout, or to check whether a completed " \
+                         "checkout produced an order; use get_cart for carts and get_order for placed " \
+                         "orders. #{OPEN_NOTE}",
+            params: { "checkout_id" => "Checkout ID returned by create_checkout. #{ID}" },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "update_checkout" => {
+            description: "Replace an open checkout's line items, discount codes or fulfillment " \
+                         "selection and return it with recalculated totals. #{REPLACE_NOTE} Use it " \
+                         "before payment only; a completed checkout can't change — adjust the order " \
+                         "with cancel_order or request_return instead. Does not charge, and any total " \
+                         "the shopper approved earlier must be re-approved. #{AUTH_NOTE}",
+            params: {
+              "checkout_id" => "Checkout ID returned by create_checkout. #{ID}",
+              "line_items" => "The checkout's complete desired contents, each {product_id:, quantity:}.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "discount_codes" => "Optional coupon codes, replacing those applied; leave out to keep the current ones.",
+              "fulfillment" => "Optional shipping or pickup selection, from the options listed on the checkout."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "complete_checkout" => {
+            description: "Charge the shopper and place the order for an open checkout — the only tool " \
+                         "here that spends money. Call it once, only after the shopper has explicitly " \
+                         "approved the exact total from get_checkout; never to preview a price. Before " \
+                         "charging it rejects anything resembling a raw card number, enforces the " \
+                         "operator's spending caps and allowlist, may require a human confirmation, " \
+                         "and re-checks stock, failing without a charge if anything is off. Returns " \
+                         "the checkout with status completed and the new order. #{AUTH_NOTE}",
+            params: {
+              "checkout_id" => "Checkout ID returned by create_checkout. #{ID}",
+              "payment_token" => "Single-use payment token from a payment handler — never a raw card number.",
+              "idempotency_key" => "#{IDEMPOTENCY_KEY} Reuse it on retry so a timeout never charges twice.",
+              "mandate" => "Optional AP2 payment mandate authorizing this charge, alongside or instead " \
+                           "of payment_token; its signature is verified before use."
+            },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "cancel_checkout" => {
+            description: "Abandon an open checkout before payment and return it with status canceled; " \
+                         "it cannot be completed afterwards. Use it when the shopper declines the " \
+                         "total; nothing has been charged yet, so no refund is needed. For a checkout " \
+                         "that already completed, use cancel_order instead. #{AUTH_NOTE}",
+            params: { "checkout_id" => "Checkout ID returned by create_checkout. #{ID}",
+                      "idempotency_key" => IDEMPOTENCY_KEY },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "get_order" => {
+            description: "Fetch a placed order by ID and return its line items with per-item " \
+                         "fulfillment status, shipping details, totals, permalink and any " \
+                         "cancellations, returns or refunds applied so far. Use it to answer " \
+                         "\"where is my order\" or to pick line item IDs for request_return or " \
+                         "refund_order; use get_checkout for anything not yet paid. #{OPEN_NOTE} " \
+                         "An unknown ID returns an empty result rather than an error.",
+            params: { "order_id" => "Order ID from a completed checkout. #{ID}" },
+            annotations: { read_only_hint: true, destructive_hint: false, idempotent_hint: true }
+          },
+          "cancel_order" => {
+            description: "Cancel an entire placed order and return it with the cancellation recorded. " \
+                         "Use it before the order ships; for part of an order, or once it has shipped, " \
+                         "use request_return. Whether a refund follows automatically depends on the " \
+                         "store — check the returned order's adjustments. Cannot be undone. #{AUTH_NOTE}",
+            params: {
+              "order_id" => "Order ID from a completed checkout. #{ID}", "idempotency_key" => IDEMPOTENCY_KEY,
+              "reason" => "Optional free-text note for the merchant, e.g. \"ordered by mistake\"."
+            },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          },
+          "request_return" => {
+            description: "File a return request for some or all line items of a placed order and " \
+                         "return the order with the request recorded as pending. It only asks — no " \
+                         "money moves until the merchant approves and a refund is issued with " \
+                         "refund_order. Use it for delivered items; use cancel_order for an order " \
+                         "that hasn't shipped. #{AUTH_NOTE}",
+            params: {
+              "order_id" => "Order ID from a completed checkout. #{ID}",
+              "line_items" => "Items to return, each {id:, quantity:} using the order line item IDs from get_order.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "reason" => "Optional free-text reason for the merchant, e.g. \"wrong size\"."
+            },
+            annotations: { read_only_hint: false, destructive_hint: false, idempotent_hint: true }
+          },
+          "refund_order" => {
+            description: "Refund some or all line items of a placed order back to the original " \
+                         "payment method and return the order with the refund recorded. Money moves " \
+                         "and it cannot be reversed. Use it once a refund is agreed; if the store " \
+                         "needs the goods back first, call request_return before this. To call off " \
+                         "a whole unshipped order, use cancel_order. #{AUTH_NOTE}",
+            params: {
+              "order_id" => "Order ID from a completed checkout. #{ID}",
+              "line_items" => "Items to refund, each {id:, quantity:} using the order line item IDs from get_order.",
+              "idempotency_key" => IDEMPOTENCY_KEY,
+              "reason" => "Optional free-text reason for the merchant."
+            },
+            annotations: { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+          }
+        }.freeze
+      end
+    end
+  end
+end

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.
@@ -387,20 +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, :policies) do
-      def initialize(id:, line_items:, currency:, totals:, discounts: Discounts.new, policies: []) = 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
@@ -429,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, :policies) do
+                           :fulfillment, :policies, :messages) do
       def initialize(id:, status:, line_items:, currency:, totals:, links:, order: nil, discounts: Discounts.new,
-                     fulfillment: CheckoutFulfillment.new, policies: [])
+                     fulfillment: CheckoutFulfillment.new, policies: [], messages: [])
         super
       end
 
@@ -442,6 +481,8 @@ module Portage
         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

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.15.0".freeze
+    VERSION = "0.16.0".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.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -193,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
@@ -204,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