feat(permalink): add ucp/version protocol version parameter

[gil--]

Description

A shopping permalink is a browser GET with no version negotiation, and links outlive their authoring (emails, QR codes, social posts). Today nothing in the URL says which UCP release the field paths and compact item tokens were written against, so a Business cannot interpret an older link deterministically once its schemas move.

This adds ucp/version as a protocol parameter in the reserved ucp root of the permalink query string. It carries the same value as ucp.version in a profile (YYYY-MM-DD), so a permalink is pinned to one release.

https://merchant.example/buy/sku_123:1?ucp/version=2026-08-25&context/postal_code=94105&continue_to=/

Platform requirements

• Include exactly one ucp/version in every generated permalink, set to the ucp.version of the profile the endpoint was discovered from (a supported_versions leaf may carry its own endpoint at its own version).
• Never a pre-release identifier.

Business requirements

• Select the release from ucp/version before resolving any field-path parameter or compact item token.
• Accept the current release and every supported_versions release; SHOULD keep resolving retired releases (resolution-only compatibility).
• Absent → resolve under a documented default release (SHOULD be the oldest supported); MUST NOT reject solely for absence.
• Unknown but well-formed → fall forward to the oldest later supported release (else newest); treat inputs that no longer apply as handled shopping errors. Never answer a browser navigation with a UCP JSON version_unsupported error.
• Malformed / duplicate values → existing malformed-permalink handling.
• Consumed on resolution; SHOULD NOT appear on the redirect URL. All other ucp/* pointers are consumed and never applied as shopping state.

Changes

• docs/specification/permalink.md: new Protocol Version (ucp/version) section; discovery, URL shape, query processing (release selection precedes classification), redirect resolution, error handling, and all examples updated.
• source/services/shopping/permalink.openapi.json: shared ucp_version query parameter on both routes; x-ucp-query-semantics.control_parameters now ["ucp/version", "continue_to"].
• source/schemas/shopping/permalink.json: description notes field paths are interpreted under the pinned release.

Opened as a draft for early feedback on the semantics (in particular default-when-absent = oldest supported, and fall-forward for unknown versions), before any Enhancement Proposal if maintainers consider this a significant change.

Category (Required)

• Core Protocol
• Governance/Contributing
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure
• Maintenance
• SDK
• Samples / Conformance
• UCP Schema
• Community Health (.github)

Related Issues

Follow-up to #523 (permalink capability).

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks (ucp-schema lint source/, scripts/validate_examples.py, cspell, markdownlint).
• I have added tests that prove my fix is effective or that my feature works. (No conformance tests cover permalinks yet.)
• New and existing unit tests pass locally with my changes.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk. (No generated model changes — only a schema description changed.)

Screenshots / Logs (if applicable)

Not a breaking change: ucp/version is optional for Businesses to receive, and existing permalinks without it resolve under the Business's default release.

[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.