Deprecate service.deployed/service.upgraded in favor of deployment.finished/targetRollout.finished #329

Context

#319 and #328 add deployment/targetRollout as the orchestration-side subjects for a rollout (queued/started/finished), separate from service, the entity-side fact of what's currently running. Per @afrittoli's review on #319, that PR intentionally does not touch service.deployed/service.upgraded, landing the new events and deciding whether to deprecate the old ones are two different decisions, and the second shouldn't block or be forced by the first. This issue is that second decision, filed separately so it can be discussed and decided independently, after there's implementation experience with deployment.*/targetRollout.*.

Proposal

Once deployment.finished/targetRollout.finished have some real-world usage, deprecate service.deployed and service.upgraded (not remove, deprecation only, actual removal would follow the normal major-version policy).

Why

pipelineRun.finished and taskRun.finished coexist today, but they're not redundant, different scopes, a parent aggregate and a per-child outcome. service.deployed/upgraded and deployment.finished/targetRollout.finished don't have that relationship: once the new events exist, service.deployed asserts the same fact at the same scope under a different name, the CDEvents equivalent of adding an execution.finished event alongside pipelineRun.finished that says the same thing again. Keeping both without deprecating either isn't a neutral "wait and see", it's an ambiguity in the vocabulary by default, since producers and consumers now have two events for one fact with no stated selection criteria between them.

This was debated at length on #319, see that thread for the full back-and-forth, including the counter-argument that some producers use service.deployed for a per-microservice-instance signal distinct from an aggregate deployment. That's addressed by deployment/targetRollout themselves: a deployment scoped to one microservice is still a deployment, so that use case doesn't require a separate event.

Process note

This repo has no existing deprecation convention to follow (no deprecated: true in any schema, no deprecation-notice pattern in the docs, no CHANGELOG). If this proposal is accepted, part of the work is establishing that convention, likely a deprecated: true field on the schema plus a notice block in continuous-deployment.md, so it's consistent for future deprecations rather than one-off phrasing.

Non-goals

This issue does not propose removing service.deployed/service.upgraded, and does not block #319 or #328.