ADR 002: UCP Protocol Alignment

Status: Implemented

Date: January 2026

Context

The Universal Commerce Protocol (UCP) was launched by Shopify and Google as an open standard for agentic commerce. It defines:

Standard discount error codes
Checkout session flows
Discount allocation methods
Transport bindings (REST, MCP, A2A)

Guardrail-sim's core use case—policy enforcement for AI agent pricing—aligns directly with UCP's discount validation patterns.

Decision

Align guardrail-sim with UCP by:

Adopting UCP error codes for discount rejection messages
Supporting UCP allocation methods (across, each)
Adding UCP-formatted MCP tools (validate_discount_code, simulate_checkout_discount)
Creating a @guardrail-sim/ucp-types package with official schema types

Alternatives Considered

Option	Pros	Cons
Full UCP alignment	Standard compatibility, easier platform integration	Additional complexity, learning curve
Partial alignment	Error codes only	Misses allocation benefits
No alignment	Simpler codebase	Misses industry standardization
Custom protocol	Full control	No ecosystem, adoption friction

Rationale

Industry momentum: Shopify and Google backing means UCP will likely become the standard
Natural fit: Discount validation is core to both UCP and guardrail-sim
MCP transport: UCP's MCP binding means our existing MCP server is already compatible
Low overhead: UCP types are additive, not replacing existing functionality
Platform compatibility: Enables integration with Shopify, Google Gemini, Microsoft Copilot

Implementation

Package Structure

packages/ucp-types/
├── src/
│   ├── discount.ts      # DiscountErrorCode, AppliedDiscount, Allocation
│   ├── checkout.ts      # CheckoutStatus, LineItem, Money
│   ├── converters.ts    # toUCPErrorCode, buildDiscountExtensionResponse
│   └── index.ts

Error Code Mapping

const VIOLATION_TO_UCP_ERROR: Record<string, UCPErrorCode> = {
  max_discount: 'discount_code_invalid',
  margin_floor: 'discount_code_invalid',
  volume_tier: 'discount_code_user_ineligible',
  stacking_not_allowed: 'discount_code_combination_disallowed',
  discount_expired: 'discount_code_expired',
  login_required: 'discount_code_user_not_logged_in',
};