feat(targetrollout): add targetRollout subject and queued/started/finished events

.spellcheck-en-custom.txt

@@ -61,6 +61,7 @@ schemauri
 specversion
 src
 subjectid
+targetrollout
 taskrun
 testcase
 testcaserun

conformance/deployment_finished.json

@@ -0,0 +1,22 @@
+{
+  "context": {
+    "specversion": "0.6.0-draft",
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
+    "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.deployment.finished.0.1.0",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "schemaUri": "https://myorg.com/schema/custom"
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "content": {
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427",
+      "environment": {
+        "id": "test123"
+      },
+      "outcome": "success"
+    }
+  }
+}

conformance/deployment_queued.json

@@ -0,0 +1,21 @@
+{
+  "context": {
+    "specversion": "0.6.0-draft",
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
+    "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.deployment.queued.0.1.0",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "schemaUri": "https://myorg.com/schema/custom"
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "content": {
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427",
+      "environment": {
+        "id": "test123"
+      }
+    }
+  }
+}

conformance/deployment_started.json

@@ -0,0 +1,21 @@
+{
+  "context": {
+    "specversion": "0.6.0-draft",
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
+    "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.deployment.started.0.1.0",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "schemaUri": "https://myorg.com/schema/custom"
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "content": {
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427",
+      "environment": {
+        "id": "test123"
+      }
+    }
+  }
+}

conformance/targetrollout_finished.json

@@ -0,0 +1,22 @@
+{
+  "context": {
+    "specversion": "0.6.0-draft",
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
+    "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.targetrollout.finished.0.1.0-draft",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "schemaUri": "https://myorg.com/schema/custom"
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "content": {
+      "target": "cdevents:v0:argo::my-org:production:cluster:prod-us-east-1",
+      "tier": "production",
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427",
+      "deploymentId": "myDeployment123",
+      "outcome": "success"
+    }
+  }
+}

conformance/targetrollout_queued.json

@@ -0,0 +1,21 @@
+{
+  "context": {
+    "specversion": "0.6.0-draft",
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
+    "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.targetrollout.queued.0.1.0-draft",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "schemaUri": "https://myorg.com/schema/custom"
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "content": {
+      "target": "cdevents:v0:argo::my-org:production:cluster:prod-us-east-1",
+      "tier": "production",
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427",
+      "deploymentId": "myDeployment123"
+    }
+  }
+}

conformance/targetrollout_started.json

@@ -0,0 +1,21 @@
+{
+  "context": {
+    "specversion": "0.6.0-draft",
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
+    "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.targetrollout.started.0.1.0-draft",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "schemaUri": "https://myorg.com/schema/custom"
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "content": {
+      "target": "cdevents:v0:argo::my-org:production:cluster:prod-us-east-1",
+      "tier": "production",
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427",
+      "deploymentId": "myDeployment123"
+    }
+  }
+}

continuous-deployment.md

@@ -14,12 +14,14 @@ Continuous Deployment (CD) events are related to continuous deployment pipelines
 
 ## Subjects
 
-This specification defines two subjects in this stage: `environment` and `service`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`.
+This specification defines four subjects in this stage: `environment`, `service`, `deployment`, and `targetRollout`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the aggregate act of applying a version of a release unit to one or more `targetRollout`s, and a `targetRollout` is the act of deploying an artifact to a single destination within a tier.
 
 | Subject | Description | Predicates |
 |---------|-------------|------------|
 | [`environment`](#environment) | An environment where to run services | [`created`](#environment-created), [`modified`](#environment-modified), [`deleted`](#environment-deleted)|
 | [`service`](#service) | A service | [`deployed`](#service-deployed), [`upgraded`](#service-upgraded), [`rolledback`](#service-rolledback), [`removed`](#service-removed), [`published`](#service-published)|
+| [`deployment`](#deployment) | The aggregate act of deploying a release unit to one or more target rollouts | [`queued`](#deployment-queued), [`started`](#deployment-started), [`finished`](#deployment-finished)|
+| [`targetRollout`](#targetrollout) | The rollout of a deployment to a single destination within a tier | [`queued`](#targetrollout-queued), [`started`](#targetrollout-started), [`finished`](#targetrollout-finished)|
 
 ### `environment`
 
@@ -43,6 +45,30 @@ A `service` can represent for example a binary that is running, a daemon, an app
 | environment | `Object` ([`environment`](#environment)) | Reference for the environment where the service runs | `{"id": "1234"}`, `{"id": "maven123, "source": "tekton-dev-123"}` |
 | artifactId | `Purl` | Identifier of the artifact deployed with this service |  `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` |
 
+### `deployment`
+
+A `deployment` is the act of applying a version of a release unit to one or more target rollouts. A deployment is a canonical SDLC fact: it represents the change to the running system that resulted from a release, as distinct in meaning from the orchestration that performed it (see [`pipelineRun`](core.md#pipelinerun)). Where a producer's pipeline execution is itself the natural deployment boundary, its `id` MAY be reused as the `deployment` subject's `id`. A deployment fans out to one or more [`targetRollout`](#targetrollout)s.
+
+| Field | Type | Description | Examples |
+|-------|------|-------------|----------|
+| id    | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | `/cd/deploy-controller` |
+| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` |
+| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` |
+
+### `targetRollout`
+
+A `targetRollout` is the act of deploying an artifact against a destination in a tier, as one part of a [`deployment`](#deployment). The destination itself, for example a regional cluster within the `production` tier or a named blue/green slot, is identified by `target`, and the logical environment it belongs to by `tier`. Multiple target rollouts may exist within a single tier. Each `targetRollout` carries a `deploymentId` reference back to its parent [`deployment`](#deployment). Together, `tier` and `target` make "what was rolled out to production, and where" a direct query over `targetRollout` events. Previously it had to be inferred from `service` events, whose `environment` reference points the other way, from the running entity back to whatever platform it happens to run on.
+
+| Field | Type | Description | Examples |
+|-------|------|-------------|----------|
+| id    | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | `/cd/deploy-controller` |
+| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` |
+| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` |
+| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` |
+| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` |
+
 ## Events
 
 ### [`environment created`](conformance/environment_created.json)
@@ -148,6 +174,105 @@ This event represents the removal of a previously deployed service instance and
 | source | `URI-Reference` | See [source](spec.md#source-subject) | | |
 | environment | `Object` ([`environment`](#environment)) | Reference for the environment where the service runs | `{"id": "1234"}`, `{"id": "maven123, "source": "tekton-dev-123"}` | ✅ |
 
+### [`deployment queued`](conformance/deployment_queued.json)
+
+This event represents a deployment that has been accepted and is waiting to begin.
+
+- Event Type: __`dev.cdevents.deployment.queued.0.1.0`__
+- Predicate: queued
+- Subject: [`deployment`](#deployment)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ |
+| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | ✅ |
+
+### [`deployment started`](conformance/deployment_started.json)
+
+This event represents a deployment controller that has begun orchestrating a rollout.
+
+- Event Type: __`dev.cdevents.deployment.started.0.1.0`__
+- Predicate: started
+- Subject: [`deployment`](#deployment)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ |
+| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | ✅ |
+
+### [`deployment finished`](conformance/deployment_finished.json)
+
+This event represents a deployment that has completed across all of its target rollouts. `deployment.finished` is the orchestration-side completion fact for a deployment, analogous to `build finished` on the CI side, and is kept separate from the entity-side fact carried by `service.deployed`. Failure semantics are all-or-nothing: if any target rollout fails, `deployment.finished` has `outcome: failure`. Consumers needing per-destination detail should inspect the individual [`targetRollout finished`](#targetrollout-finished) events.
+
+- Event Type: __`dev.cdevents.deployment.finished.0.1.0`__
+- Predicate: finished
+- Subject: [`deployment`](#deployment)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ |
+| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | ✅ |
+| outcome | `String (enum)` | Outcome of the finished deployment | `success`, `failure`, `cancel`, `error` | ✅ |
+
+### [`targetRollout queued`](conformance/targetrollout_queued.json)
+
+This event represents a deployment to a specific target rollout that has been scheduled.
+
+- Event Type: __`dev.cdevents.targetrollout.queued.0.1.0-draft`__
+- Predicate: queued
+- Subject: [`targetRollout`](#targetrollout)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` | ✅ |
+| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` | ✅ |
+| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ |
+| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ |
+
+### [`targetRollout started`](conformance/targetrollout_started.json)
+
+This event represents a deployment to a specific target rollout that has begun.
+
+- Event Type: __`dev.cdevents.targetrollout.started.0.1.0-draft`__
+- Predicate: started
+- Subject: [`targetRollout`](#targetrollout)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` | ✅ |
+| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` | ✅ |
+| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ |
+| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ |
+
+### [`targetRollout finished`](conformance/targetrollout_finished.json)
+
+This event represents a deployment to a specific target rollout that has completed. `failureType` categorizes the failure reason when `outcome` is `failure`, letting consumers distinguish a policy gate, build, evaluation, deployment, or analysis failure without producer-specific convention.
+
+- Event Type: __`dev.cdevents.targetrollout.finished.0.1.0-draft`__
+- Predicate: finished
+- Subject: [`targetRollout`](#targetrollout)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` | ✅ |
+| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` | ✅ |
+| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ |
+| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ |
+| outcome | `String (enum)` | Outcome of the finished target rollout | `success`, `failure`, `cancel`, `error` | ✅ |
+| failureType | `String (enum)` | Category of failure, only present when `outcome` is `failure` | `gate`, `build`, `evaluation`, `deployment`, `analysis` | |
+
 ### [`service published`](conformance/service_published.json)
 
 This event represents an existing instance of a service that has an accessible URL for users to interact with it. This event can be used to let other tools know that the service is ready and also available for consumption.

schemas/_defs/deployment.json

@@ -0,0 +1,18 @@
+{
+  "$id": "cdevents/_defs/deployment",
+  "term": "Deployment",
+  "definition": "A Deployment is the act of applying a version of a release unit to one or more target rollouts. A deployment is a canonical SDLC fact, and it is not the pipeline that performed the deployment, but the change to the running system that resulted from it.",
+  "notes": [
+    "A Deployment fans out to one or more TargetRollouts",
+    "A Deployment is not the pipeline or tooling that executed it",
+    "deployment/targetRollout separate the orchestration act of deploying from the entity fact of a running service, mirroring the build/artifact split in CI"
+  ],
+  "examples": [
+    "Deploying myapp v1.2.3 to the production environment across multiple regions",
+    "A Spinnaker pipeline execution that rolls out a service to multiple Kubernetes clusters"
+  ],
+  "counterExamples": [
+    "The pipeline that performed the deployment",
+    "An individual rollout to a single target (that is a TargetRollout)"
+  ]
+}

schemas/_defs/finished.json

@@ -0,0 +1,20 @@
+{
+  "$id": "cdevents/_defs/finished",
+  "term": "Finished",
+  "definition": "Indicates that execution of an entity has ended, regardless of outcome. The outcome field on the event conveys whether execution succeeded or failed.",
+  "notes": [
+    "A finished event does not imply successful execution.",
+    "The outcome field must be inspected to determine success or failure.",
+    "A finished event is terminal — no further lifecycle events follow for this entity."
+  ],
+  "examples": [
+    "A deployment completing across all target rollouts",
+    "A target rollout completing at its destination",
+    "A pipeline run terminating with success or failure"
+  ],
+  "counterExamples": [
+    "Intermediate execution states",
+    "Progress or partial completion signals",
+    "Cancellation requests (the finished event is emitted after cancellation is complete)"
+  ]
+}