feat: add state-bound Offer extension for Cart proposals

[arjun2075]

Summary

Implements the smallest structural/transport portion of #738:

• adds a state-bound Offer extension for Cart (dev.ucp.shopping.offer);
• represents the Business-computed proposed target line_items;
• binds the Offer to applies_to.cart_id + applies_to.state_ref;
• identifies the Offer operationally using id + revision;
• adds a reference-based apply_offer operation;
• keeps REST and MCP semantics aligned;
• reuses normal UCP idempotency;
• keeps the returned Cart authoritative.

Why

UCP can represent a Cart and let the Platform update it, but has no explicit
representation for:

given this exact Cart state, the Business proposes this resulting Cart state.

This turns the design settled in #702 into an executable schema/transport slice.

The extension follows the discount.json composition pattern ($defs + allOf
over cart.json) rather than modifying the Cart schema. proposed_update.line_items
reuses existing Cart full-replacement semantics, so there is no second mutation
vocabulary.

apply_offer deliberately diverges from the discount precedent, which routes
application through the normal cart update request. A discount code is just a
string, so there is nothing precomputed to echo. An Offer's value is that the
Business already computed the resulting state, so requiring the Platform to
resubmit those line_items would duplicate authoritative state and create a
drift case between the stored proposal and the resubmitted one. The Platform
references offer_id + revision; the Business applies the exact stored revision.

Key invariant

applicable =
    source state still matches
    AND not expired
    AND Business can still honor the proposal

These are conjunctive, so a stale-but-unexpired Offer fails closed. Applying one
Offer moves the Cart to a new state and makes sibling Offers bound to the previous
state stale.

Runtime conditions are expressed as normative operation semantics rather than
forced into JSON Schema, since they depend on live Cart state.

Scope deliberately deferred

This PR does not implement:

• commercial-intervention provenance from Proposal: Preserve commercial-intervention provenance across Catalog → Offer → Cart → Checkout #724;
• generic Cart or Checkout versioning (see [Spec] Concurrent checkout updates can cause silent data loss - need ETag/If-Match support #113);
• recurrence/subscription modeling;
• cryptographic digest/signature infrastructure — id + revision is operational
  identity here; evidence identity is left to a shared convention;
• generic mutation / JSON Patch semantics;
• SDK, sample, or conformance implementations.

state_ref is intentionally opaque and implementation-assigned. If another
extension needs the same state identity, that seems like the right point to
introduce a shared Cart primitive rather than inventing one here.

Testing

Commands actually run, with results:

Command	Result
ucp-schema lint source/	125 files checked, all passed
uv run python scripts/validate_examples.py --schema-base source/schemas/	343 passed, 0 failed, 0 errors
uv run python scripts/test_validate_examples.py	52 passed, 0 failed
uv run yamllint -c .github/linters/.yamllint.yml .	pre-existing line-length warnings only
cspell lint (3 changed files)	0 issues
DOCS_MODE=spec uv run mkdocs build --strict	47 warnings, byte-identical to main baseline; no new warnings

Additional local verification (ad-hoc, not committed): resolved every $ref in
both service documents; confirmed the extension composes against cart.json and
validates a full Offer example; confirmed each decision-relevant field is required,
that an empty state_ref is rejected, that presentation is optional, and that
impact.total_delta accepts negative values; confirmed REST and MCP take the same
{id, offer_id, revision} inputs, both require idempotency, and neither carries a
request body.

Relationship

Implements the structural/transport portion of #738. Design history in #702.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[arjun2075]

Hi maintainers — following up on this Offer extension PR. The CLA check is passing, and the PR is currently awaiting the required governance approvals.

The scope is limited to the state-bound Offer schema and REST/MCP apply_offer operation from #738. Commercial-intervention provenance (#724) and the broader lifecycle contract (#788) remain separate.

Could someone from the TC take an initial pass, or point me to the appropriate reviewer? Feedback on the reference-based application operation and source-state validity semantics would be particularly helpful. Happy to address changes or narrow the scope further.