docs: clarify UCP core release versioning contract

[igrigorik]

UCP intentionally gave services, capabilities, and extensions their own version fields so they could evolve independently from ucp.version. The specification described that flexibility as part of the protocol model.

In practice, UCP's publishing and certification process settled on an atomic release contract: each dated core release ships its services and transport bindings, capabilities, extensions, and shared schemas as one tested snapshot. This PR codifies that current contract rather than continuing to imply independent release schedules that UCP does not currently exercise.

The release contract

For a selected release D:

1. The Platform resolves one exact Business profile for D, either the current profile or a supported_versions leaf whose ucp.version matches its map key.
2. ucp.version = D selects the UCP core snapshot published under D.
3. Every UCP-authored service, capability, and extension declaration in that profile carries D.
4. Exact capability intersection selects the active capabilities and extensions from the chosen snapshot.
5. requires.protocol and requires.capabilities verify the selected versions; they do not select replacements.

Business profiles
  ├── current profile
  └── supported_versions[D]
                │
                ▼
       exact profile for D
                │
                ▼
       UCP core snapshot D
                │
                ▼
   exact capability intersection
                │
                ▼
       verify requires ranges

Transport descriptions remain versioned release artifacts. OpenAPI and OpenRPC info.version identifies the artifact published under D; it is not another profile negotiation axis. This does not prevent transport specifications from evolving—it defines how UCP currently bundles them into a core release.

The individual version fields remain in place. They preserve the existing wire shape and leave room for UCP to define independently versioned core components in a future contract without requiring a profile migration.

Independent contracts

Third-party extensions and payment handlers retain their author-controlled versions and release cadence. The build hook now stamps the release version only onto UCP-authored dev.ucp.* schemas, making that ownership boundary explicit without changing current generated output. The PR also clarifies that dev.ucp.* capabilities are governed by the UCP Tech Council responsible for their domain.

Documentation (re)structure

To avoid repeating subtly different rules across the documentation:

• Protocol Version owns exact profile discovery and supported_versions.
• Capability Versions owns exact capability intersection.
• Component Versioning and Release Snapshots owns release-D alignment and version ownership.
• Versioning owns the release-branch and backport workflow.
• Core Concepts and Schema Authoring summarize the relevant rules and link to their normative definitions.

Compatibility

This is a contract clarification, not a wire migration.

• No profile shape changes.
• No fields added or removed.
• No required-field changes.
• No payload-validation changes.
• No change to current generated artifacts.
• Schema changes are descriptions only.
• Existing illustrative names, URLs, versions, and placeholders are unchanged.

Related Issues

Closes #499. Supersedes #418.

---

Checklist

• Documentation: Updates to README, or documentations regarding schema or capabilities.
• Infrastructure: CI/CD, Linters, or build scripts.
• I have followed the Contributing Guide
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.

[jingyli]

Thanks for proposing the clarification! Given this PR, it would also significantly simplify version's correlation to UCP's releases (related RFC - #499), especially if the releases are going to be done at a fixed/regular cadence.

But curious if we have some early thoughts around: How will the first release for new services look like? Let's hypothetically say a new service (i.e. food ordering) has an approved spec tomorrow, will they need to wait until the next official release of UCP to stamp a version D on their capabilities? Or will these be considered as backwards-compatible changes (since they are net new capabilities) and be backported into a previous stable release?

[igrigorik]

@jingyli great questions & flags, clarified in 7d8b56b — ptal.

But curious if we have some early thoughts around: How will the first release for new services look like? Let's hypothetically say a new service (i.e. food ordering) has an approved spec tomorrow, will they need to wait until the next official release of UCP to stamp a version D on their capabilities? Or will these be considered as backwards-compatible changes (since they are net new capabilities) and be backported into a previous stable release?

Both paths are possible under our contract. If a net-new service is a backwards-compatible addition, then a newly approved vertical either:

1. ships in the next release D2 and declares D2 (default), or
2. if approved for backport, lands on the maintained release/D branch, declares D, and the snapshot is re-certified.

Practically, I would push us to synchronize releases and snap to common dates rather than cut per-vertical releases — the shared date is what guarantees a common core and cross-service interop. Today that cadence is quarterly (targeting ~12 weeks), so in your example food ordering slots into the next release train rather than waiting indefinitely. The cadence itself is release-process policy, not codified in the spec -- the GC can choose to adjust the schedule.

[jingyli]

Thanks @igrigorik for the updates in 7d8b56b!

We added one proposal (https://github.com/Universal-Commerce-Protocol/ucp/pull/614/changes#r3694051647) to provide platforms, who may support multiple versions, flexibility to select which business profile they would like to negotiate against and not always be forced into choosing the "current" version under the current wording - @sinhanurag @gsmith85 FYI

Also ack on #614 (comment), personally I prefer the backporting route to minimize having to wait for D2, especially in the rare instances where a vertical may have just missed the release train.

[igrigorik]

@jingyli landed, ready for final pass!

[gsmith85]

LGTM! Gave it one last read through, it looks great. Thanks @igrigorik for formalizing the core release snapshot contract. This provides clear alignment between ucp.version, profile discovery, and component artifacts.

[raginpirate]

Almost all nits, one concern about our backporting stance for breaking changes. (#614 (comment))

[igrigorik]

@raginpirate good nits! Updated: dac71fb.

[raginpirate]

🚀

[igrigorik]

@amithanda good catch on both comments — working through them surfaced a few related gotchas (notice-process ordering for security fixes, hosting policy not covering schema artifacts), landed updated wording in 1e1dea06.

[amithanda]

f5581c8 covers both of my comments well. The skew paragraph states the part I
was after, that D is amended in place and earlier copies stay valid, and
grounding refresh behavior in standard HTTP caching plus the new
ETag/Last-Modified validator is a better answer than the one I proposed, it
makes skew self-correcting for runtime fetchers rather than merely documented.
Extending Hosting to cover schema and transport-description artifacts closes the
gap that made skew undetectable in the first place.

The consumer-side rejection rule reads right, and keeping it entity-scoped means
one malformed entry does not invalidate the full profile.

Approving!