feat: add policies[] to cart, checkout, catalog, and order (#572)

* add policies[] to cart, checkout, and catalog

Introduce `policies[]`, a core response field carrying business
rules about the items — return/refund terms, warranty, and custom
policies — on cart, checkout, and catalog (search, lookup, get_product)
responses. Entries target items with RFC 9535 JSONPath via `applies_to`
(omitted = whole response; most-specific match wins).

Key design decisions:

- Core, not an extension: policies are facts the business expresses directly;
  reading them requires no capability negotiation.
- Cross-surface: the same field applies on catalog, cart, and checkout
  responses.
- Open, reverse-DNS `type` vocabulary (`dev.ucp.shopping.policy.refund`,
  `.warranty`; custom types in the author's own domain). Platforms tolerate
  unknown types — no closed enum, no central registry, no namespace collisions.
- Open envelope + discriminated overlay: the base validates any policy;
  `refund` layers structured fields (`window` xor `final_sale`, mutually
  exclusive) via an allOf if/then. Adding a well-known overlay is additive.
- `type` + `description` are the required floor (description MUST, stated in
  prose) so any policy is presentable without modeling its type. No `id`:
  policies are referenced positionally and by `url`, matching `discount`.
- Disclosure lives in messages, not policies — a policy never forces display.
  When a term must be shown, the business emits a `messages[]` warning with
  `presentation: "disclosure"`, linked to its policy by `code == type` at the
  same target. One forcing channel, consistent with existing Prop 65 notices.
- Complementary to `links[]`: policies are the structured layer, `links[]` the
  always-present fallback; a policy omitting `url` resolves the `links[]` entry
  of the corresponding type.

* define policies[] resolution & precedence rules

A response can carry several policies of the same `type` — a store-wide
default plus per-item overrides. A reader needs one deterministic answer
to "which policy governs this node?", or the same document renders
differently across platforms. The initial cut left that as a one-line
"most-specific match wins" and embedded a refund sketch in the type.
This commit makes the resolution rule precise and pulls the refund
domain body out to its own proposal, so the generic container can stand
on its own as infrastructure.

`applies_to` binds a policy to nodes by RFC 9535 JSONPath, relative to
the response root — the convention `messages[].path` and
`discount.allocations[].path` already use. RFC 9535 also gives us the
two instruments precedence needs, so we don't build a parallel system:

- a Normalized Path (Section 2.7) is a node's canonical identity:
  `$.products[0].variants[3]` is the segment sequence `products, 0,
  variants, 3`, and the root `$` is the empty sequence;
- a singular query (Section 2.3.5.1) is an expression that names exactly
  one node using only name and index selectors, as opposed to a filter,
  wildcard, or slice, which match a set.

A direct id-reference would need neither, but it also can't express the
thing policy resolution is mostly about: cascade. A target covers the
node it names and everything nested under it, so `$.products[0]` governs
a product and all its variants in a single entry, while
`$.products[0].variants[3]` overrides just that variant. An id names one
item; the cascade would have to be enumerated node by node.

For a given `type`, among the policies whose target covers a node:

1. A target covers a node when the node it matches is that node or an
   ancestor of it — equivalently, when the matched node's Normalized
   Path is a prefix of the target's. That prefix length is its depth (a
   Response-wide policy targets the root `$`, so depth 0).
2. Score each policy by its deepest covering match as `(depth,
   precision)`: depth first; precision is 1 for a singular query and 0
   for a Set match.
3. The greatest score governs — deepest wins, and at equal depth a
   singular query outranks a Set match.

So a variant-level target (depth 4) beats a product-level one (depth 2)
beats a response-wide default (depth 0); and where two reach the same
node at the same depth, `$.products[0]` (singular) beats
`$.products[?@.category=='electronics']` (a set).

Depth first is deliberate: ranking selector kinds regardless of nesting
would let a wildcard on a variant lose to an index on the product,
inverting the cascade. And we stop at the singular-vs-set distinction
because that is the only ordering RFC 9535 defines.

When two same-`type` policies cover a node at the same depth and
precision — two overlapping Set matches, or two Response-wide entries —
the outcome is undefined. This is model-independent: naming the node by
an id would collide the same way, because the author has said two
contradictory things about one node. A Business MUST NOT publish such a
collision; a Platform MUST surface a warning rather than resolve it
silently.

* bind policy disclosures to the governing policy

The disclosure pairing said a disclosure pairs with "the policy" at its
`path` node, joined by `code == type`. With precedence now defined,
that's ambiguous when several policies of the same `type` cover the
node. Tie the pairing to precedence instead: a disclosure pairs with the
policy that governs its node — the one precedence selects — which is at
most one, so the pairing is unambiguous.

Naming the governing policy also makes two authoring drifts nameable,
since `messages[]` and `policies[]` are authored separately:

- Contradiction — the notice disagrees with its policy. They are two
  statements about one node, so a disclosure's content MUST agree with
  the policy it pairs with.
- Dangling — `code` names a `type` no policy covers at the node, so the
  pairing resolves to nothing. The notice still displays, so this is a
  SHOULD: requiring a backing policy would couple the two arrays and
  forbid force-displaying a notice without a structured policy.

Neither carries a Platform MUST-warn. That stays reserved for precedence
collisions — the case that is both machine-detectable and leaves
resolution undefined. A contradiction is free text on the message side,
and a dangling pairing is benign.

* feat: add policies[] to order, decouple refund

   - Add `policies[]` to `order` as a read-only snapshot of the policies
     that applied at checkout (`ucp_request: omit`), mirroring how
     `order.attribution` snapshots checkout data. Completes the catalog ->
     cart -> checkout -> order lifecycle; returns are post-purchase, so the
     order is the durable home for their terms.
   - Remove the refund `allOf` overlay from `policy.json` and delete the
     now-empty `policy_refund.json`. Core stays a pure generic container;
     the refund type attaches its body via extension composition (#257).
   - Type `policy.type` via `$ref` to `reverse_domain_name.json`, so the
     reverse-DNS format is enforced rather than described only in prose.
   - State in Precedence that a Platform MUST NOT merge same-type policy
     bodies: a consumer cannot infer combine-vs-replace semantics, so it
     resolves a single governing policy by structure alone. Composition is
     authored into the most-specific policy, not resolved at read time.
   - Collapse the disclosure-pairing passage to one paragraph plus two
     numbered rules (editorial).

* docs: rename refund policy type to return, soften collisions

   - Rename the well-known type `dev.ucp.shopping.policy.refund` to
     `.return`. schema.org models this as MerchantReturnPolicy (return is
     the head concept; refundType is one outcome facet), so `refund` named
     the policy after a facet rather than the container. The refund /
     exchange / credit outcomes live in the type body defined by #257.

   - Soften the collision rule: a Platform SHOULD (was MUST) flag an
     authoring collision rather than resolve it silently, treatment left
     to the Platform. A MUST-surface obligation was inconsistent with
     policy presentation being optional and had no defined audience. The
     Business MUST NOT publish a collision is unchanged.

Author: igrigorik

docs/specification/cart.md

@@ -286,3 +286,12 @@ are estimates; accurate taxes are computed at checkout.
 ### Link
 
 {{ schema_fields('types/link', 'checkout') }}
+
+### Policy
+
+Policies (return/refund terms, warranty, and the like) that apply to the items
+in this cart. JSONPath targets in `applies_to` are relative to
+this response root (e.g., `$.line_items[0]`). See
+[Policies](overview.md#policies) for the full model.
+
+{{ schema_fields('types/policy', 'cart') }}

docs/specification/catalog/index.md

@@ -150,6 +150,15 @@ as the first element. Platforms SHOULD treat the first element as featured.
 
 {{ schema_fields('types/rating', 'catalog') }}
 
+### Policy
+
+Policies (return/refund terms, warranty, and the like) that apply to the
+products in a catalog response. JSONPath targets in `applies_to` are
+relative to the response root — `$.products[N]` for search and batch lookup,
+`$.product` for get_product. See [Policies](../overview.md#policies) for the full model.
+
+{{ schema_fields('types/policy', 'catalog') }}
+
 ## Actions
 
 Catalog Search, batch Lookup, and successful Get Product responses can include

docs/specification/checkout.md

@@ -573,7 +573,9 @@ downgrading to a notice.
 * **SHOULD** use the `path` field to associate disclosures with the
   relevant component in the response.
 * **SHOULD** provide a `code` that identifies the disclosure category
-  (e.g., `prop65`, `allergens`, `energy_label`).
+  (e.g., `prop65`, `allergens`, `energy_label`). When the disclosure renders a
+  structured `policies[]` entry, the `code` **MUST** equal that policy's `type`
+  to link the two (see [Policies](overview.md#policies)).
 * **SHOULD** provide `image_url` when the disclosure has an associated
   visual element (e.g., warning symbol, energy class label).
 * **SHOULD** provide `url` when a reference link is available for the
@@ -945,6 +947,15 @@ Businesses **MAY** define custom types for domain-specific needs. Platforms
 **SHOULD** handle unknown types gracefully by displaying them using the `title`
 field or omitting them.
 
+### Policy
+
+Policies (return/refund terms, warranty, and the like) that apply to the items
+in this checkout. JSONPath targets in `applies_to` are relative to
+this response root (e.g., `$.line_items[0]`). See
+[Policies](overview.md#policies) for the full model.
+
+{{ schema_fields('types/policy', 'checkout') }}
+
 ### Message
 
 {{ schema_fields('message', 'checkout') }}

docs/specification/order.md

@@ -94,6 +94,11 @@ Businesses MAY surface a snapshot of the originating checkout's
 `order.attribution`. See [Attribution](overview.md#attribution) for the
 underlying contract.
 
+### Policies
+
+Businesses MAY surface a snapshot of the policies that applied at checkout on
+the order. See [Policies](overview.md#policies) for the underlying contract.
+
 ### Adjustments
 
 **Adjustments** are post-order events that exist independently of

docs/specification/overview.md

@@ -2252,6 +2252,235 @@ Detailed definitions for endpoints, schemas, and valid extensions for each
 capability are provided in their respective specification files. Extensions are
 typically versioned and defined alongside their parent capability.
 
+## Policies
+
+A policy is a business rule — return terms, warranty, subscription
+terms, and the like — that applies to the items in a response at the time of
+purchase, carried in a core `policies[]` array alongside `messages[]` and
+`links[]`.
+
+### Policy types
+
+A Business publishes well-known and custom policies. Every policy carries a
+`type` drawn from an open, reverse-DNS vocabulary.
+
+| Well-known type | Description |
+| :-- | :-- |
+| `dev.ucp.shopping.policy.return` | Return terms. |
+| `dev.ucp.shopping.policy.warranty` | Warranty terms. |
+
+A Business **MAY** define custom types in its own domain (e.g.,
+`com.example.policy.price_match`) and **MAY** add type-specific fields that a
+Platform modeling that `type` can read for structured context. Because the
+vocabulary is open, a Platform **MUST** tolerate unknown `type` values,
+presenting the policy from its `description` (see
+[Presenting policies](#presenting-policies)).
+
+### Targeting
+
+`applies_to` is an array of RFC 9535 JSONPath expressions, evaluated relative to
+the **embedding response root** — the same convention `messages[].path` uses.
+The root differs by surface: `$.line_items[N]` on cart, checkout, and order,
+`$.products[N]` on catalog search and lookup, `$.product` on get_product. A
+policy targets nodes in one of three forms:
+
+- **Singular query** — an expression naming exactly one node using only name
+  and index selectors ([RFC 9535
+  §2.3.5.1](https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.1)), e.g.
+  `$.line_items[2]`.
+- **Set match** — a filter, wildcard, or slice matching a set of nodes, e.g.
+  `$.products[?@.category=='electronics']`.
+- **Response-wide** — an omitted `applies_to`; the policy applies to the entire
+  response. This is the common case: a single site-wide policy is one entry with
+  no targeting, never repeated per item.
+
+A target covers the node it names **and everything nested under it** — a policy
+on `$.products[0]` covers the product and all its variants, while one on
+`$.products[0].variants[3]` covers only that variant. To give one variant a
+different term, a Business names it directly; the narrower target wins where the
+two overlap (see Precedence, below).
+
+### Precedence
+
+Policies of **different** `type` are independent: each applies on its own, so a
+single node can carry a warranty policy and a price-match policy at once.
+
+Policies of the **same** `type` can contest a node. When they do, exactly one
+governs and **replaces** the rest — a Platform **MUST NOT** merge their bodies.
+Merging would mean inferring whether policies combine or replace, which a
+Platform cannot read from the data; resolution selects one governing policy by
+structure alone. When terms genuinely stack, the Business folds them into the
+most-specific policy — composition is authored, not resolved. Resolving which
+one governs is a **longest-prefix match** against the response in hand.
+
+Every node has a canonical identity: its **Normalized Path** ([RFC 9535
+§2.7](https://www.rfc-editor.org/rfc/rfc9535#section-2.7)), the sequence of
+segments locating it from the root — `$.products[0].variants[3]` is `products`,
+`0`, `variants`, `3`, and the root `$` is the empty sequence. A target
+**covers** a node when a node it matches is that node or an ancestor of it —
+equivalently, when the matched node's Normalized Path is a prefix of the target
+node's. The length of that prefix is its **depth**.
+
+To resolve which policy of a given `type` governs a node:
+
+1. Take the same-`type` policies with a target covering the node. A
+   Response-wide policy (omitted `applies_to`) targets the root `$`, so it
+   covers every node at depth 0. If none cover the node, no policy of that
+   `type` governs it.
+2. Score each by its **deepest** covering match as the pair `(depth,
+   precision)`: *depth* is that match's prefix length; *precision* is `1`
+   when the target is a **singular query** ([RFC 9535
+   §2.3.5.1](https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.1) — name and
+   index selectors only, so it names a single node) and `0` when it is a **Set
+   match** (filter, wildcard, or slice). If several covering matches share the
+   greatest depth, take the greatest precision among them.
+3. The policy with the greatest score governs — **depth first, then
+   precision**.
+4. When the greatest score is shared, the outcome is **undefined**. A tie
+   requires two policies to cover the node at the same depth and precision;
+   since a node has one ancestor at each depth, they contest the *same* node —
+   two overlapping Set matches, or two Response-wide entries of one `type`. This
+   is an authoring error, not an artifact of path targeting: naming the node by
+   an id would collide the same way. A Business **MUST NOT** publish such a
+   collision. Because resolution is undefined, a Platform **SHOULD** flag the
+   ambiguity rather than resolve it silently; the treatment is left to the
+   Platform.
+
+### Absent vs. empty
+
+When `policies[]` is absent or empty for a given response, the Platform
+**SHOULD** refer to the general policy resources in `links[]` (e.g.,
+`refund_policy`, or per-variant `seller.links` in catalog).
+
+### Presenting policies
+
+Policies describe the business rules applied to the items. A Platform **MAY**
+reason over them for its own decisions — eligibility, a computed return
+deadline. So that a policy is always presentable — even by a Platform that does
+not model its `type` — a Business **MUST** provide a `description`, a
+human-readable summary a Platform **MAY** surface to the Buyer. Presenting a
+policy is optional.
+
+When a Business **requires** a policy to be shown to the Buyer — a final-sale
+item, a regulatory notice — it **MUST** emit a `messages[]` warning that:
+
+- sets `presentation: "disclosure"`, so the Platform displays the content and
+  cannot hide or dismiss it (see
+  [Warning Presentation](checkout.md#warning-presentation));
+- sets `path` to the item the notice concerns; and
+- sets `code` to the policy's `type`, linking the notice to its policy.
+
+The warning is type-agnostic: the Platform shows its content without
+understanding the policy behind it, so one channel handles everything from
+final-sale terms to regulatory notices.
+
+A disclosure pairs with the policy that **governs** its `path` node — the one
+[Precedence](#precedence) selects when several policies of the same `type` cover
+that node. Precedence yields at most one, so the pairing is unambiguous. Two
+rules apply:
+
+1. A disclosure's content **MUST** agree with the policy it pairs with — the
+   notice and the policy are two statements about the same node.
+2. A disclosure **SHOULD** resolve to a governing policy: when its `code` names
+   a `type` no policy covers at that node, the notice still displays, but
+   nothing structured stands behind it.
+
+For example, an engraved line item is final sale. A response-wide return policy
+applies to the whole cart, but the item-scoped final-sale policy governs line 2,
+so the disclosure on that line pairs with it — notice and policy agree:
+
+<!-- ucp:example schema=shopping/checkout target=$.policies -->
+```json
+[
+  {
+    "type": "dev.ucp.shopping.policy.return",
+    "description": { "plain": "Free 30-day returns from delivery." }
+  },
+  {
+    "type": "dev.ucp.shopping.policy.return",
+    "description": { "plain": "This engraved item is final sale and cannot be returned." },
+    "applies_to": ["$.line_items[2]"],
+    "url": "https://example.com/returns#final-sale"
+  }
+]
+```
+
+<!-- ucp:example schema=shopping/checkout target=$.messages -->
+```json
+[
+  {
+    "type": "warning",
+    "code": "dev.ucp.shopping.policy.return",
+    "path": "$.line_items[2]",
+    "presentation": "disclosure",
+    "content": "This engraved item is final sale and cannot be returned."
+  }
+]
+```
+
+### Relationship to `links[]`
+
+`links[]` and `policies[]` are complementary. `links[]` is the always-present
+fallback — a labeled URL, response-wide, usually one per type. `policies[]` is
+the structured layer when available — typed, with optional per-item
+`applies_to` targeting and multiple entries (a response-wide default plus
+overrides).
+
+### Examples
+
+A site-wide warranty with a per-item override, both the same `type`. On line
+item 2 the singular query governs, overriding the Response-wide default; every
+other line item keeps it:
+
+<!-- ucp:example schema=shopping/checkout target=$.policies -->
+```json
+[
+  {
+    "type": "dev.ucp.shopping.policy.warranty",
+    "description": { "plain": "1-year limited warranty on all items." }
+  },
+  {
+    "type": "dev.ucp.shopping.policy.warranty",
+    "description": { "plain": "3-year extended warranty on this item." },
+    "applies_to": ["$.line_items[2]"]
+  }
+]
+```
+
+A Set match overridden by a singular query, again the same `type`. Product 0 is
+an electronics item, so both entries reach it; the singular query governs
+there, while other electronics keep the 2-year term:
+
+<!-- ucp:example schema=shopping/catalog_search op=search direction=response target=$.policies -->
+```json
+[
+  {
+    "type": "dev.ucp.shopping.policy.warranty",
+    "description": { "plain": "2-year warranty on electronics." },
+    "applies_to": ["$.products[?@.category=='electronics']"]
+  },
+  {
+    "type": "dev.ucp.shopping.policy.warranty",
+    "description": { "plain": "5-year manufacturer-certified warranty on this item." },
+    "applies_to": ["$.products[0]"]
+  }
+]
+```
+
+A custom `type` a Platform does not model is still presentable from its
+`description`:
+
+<!-- ucp:example schema=shopping/catalog_search op=search direction=response target=$.policies -->
+```json
+[
+  {
+    "type": "com.example.policy.price_match",
+    "description": { "plain": "We match a competitor's lower price for 14 days after purchase." },
+    "applies_to": ["$.products[0]"]
+  }
+]
+```
+
 ## Security
 
 ### Transport Security

source/schemas/shopping/cart.json

@@ -122,6 +122,14 @@
       "description": "Optional merchant links (policies, FAQs).",
       "ucp_request": "omit"
     },
+    "policies": {
+      "type": "array",
+      "items": {
+        "$ref": "types/policy.json"
+      },
+      "description": "Policies (e.g., return/refund terms) that apply to the items in this cart. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`.",
+      "ucp_request": "omit"
+    },
     "continue_url": {
       "type": "string",
       "format": "uri",

source/schemas/shopping/catalog_lookup.json

@@ -86,6 +86,13 @@
             "$ref": "../common/types/message.json"
           },
           "description": "Errors, warnings, or informational messages about the requested items."
+        },
+        "policies": {
+          "type": "array",
+          "items": {
+            "$ref": "types/policy.json"
+          },
+          "description": "Policies (e.g., return/refund terms) that apply to the products in this response. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`."
         }
       }
     },
@@ -180,6 +187,13 @@
             "$ref": "../common/types/message.json"
           },
           "description": "Warnings or informational messages about the product (e.g., price recently changed, limited availability)."
+        },
+        "policies": {
+          "type": "array",
+          "items": {
+            "$ref": "types/policy.json"
+          },
+          "description": "Policies (e.g., return/refund terms) that apply to this product. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`."
         }
       }
     }

source/schemas/shopping/catalog_search.json

@@ -61,6 +61,13 @@
             "$ref": "../common/types/message.json"
           },
           "description": "Errors, warnings, or informational messages about the search results."
+        },
+        "policies": {
+          "type": "array",
+          "items": {
+            "$ref": "types/policy.json"
+          },
+          "description": "Policies (e.g., return/refund terms) that apply to the products in these search results. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`."
         }
       }
     }

source/schemas/shopping/checkout.json

@@ -106,6 +106,14 @@
       "description": "Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.",
       "ucp_request": "omit"
     },
+    "policies": {
+      "type": "array",
+      "items": {
+        "$ref": "types/policy.json"
+      },
+      "description": "Policies (e.g., return/refund terms) that apply to the items in this checkout. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`.",
+      "ucp_request": "omit"
+    },
     "expires_at": {
       "type": "string",
       "format": "date-time",

source/schemas/shopping/order.json

@@ -96,6 +96,14 @@
       "$ref": "types/totals.json",
       "description": "Different totals for the order."
     },
+    "policies": {
+      "type": "array",
+      "items": {
+        "$ref": "types/policy.json"
+      },
+      "description": "Snapshot of the policies that applied to the items at checkout, captured on the order as a durable record. `applies_to` targets are relative to the response root.",
+      "ucp_request": "omit"
+    },
     "messages": {
       "type": "array",
       "items": {