margo · matlec · Aug 25, 2026
@@ -22,6 +22,8 @@ classes:
         description: >-
           The unique identifier UUID of the deployment specification.
           Needs to be assigned by the Workload Fleet Manager.
+          When the Workload Fleet Manager changes the content of an existing deployment, the `id` stays the same and the digest changes.
+          A different `id` identifies a different deployment.
         required: true
         range: string
         pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"

@@ -37,6 +37,7 @@ POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status
 |-----------------|-----------------|-----------------|-----------------|
 | deploymentId    | string    | Y    | The unique identifier UUID of the deployment specification. Needs to be assigned by the Workload Fleet Management Software. |
 | deviceId        | string    | N*    | Id of the device hosting the deployment. Includes the full device hierarchy if applicable. <br/> * This attribute is required when reporting on behalf of a child-device. |
+| adoptedManifestVersion | number    | Y    | The [manifestVersion](./desired-state.md#endpoints---state-manifest) of the most recent state manifest the WFM client has adopted for this deployment. See the [Adopted Manifest Version](#adopted-manifest-version) section below.|
 | status          | []status    | Y    | Element that defines overall deployment status. See the [Status Attributes](#status-attributes) section below.|
 | components      | []components    | Y    | Element that defines the individual component's deployment status. See the [Component Attributes](#component-attributes) section below.|
 
@@ -83,12 +84,25 @@ When the error is not generated by a see-thru gateway, the source of the `compon
 
 When the error used is a reserved code for a gateway-generated error, the `source` attribute MUST be set to the id of the gateway, with its full hierarchy if applicable.
 
+#### Adopted Manifest Version
+
+A state manifest defines a revision of each deployment it carries. A WFM client has adopted that revision when it holds it and has begun applying it. Adoption is independent of the outcome. The `status.state` attribute carries the outcome.
+
+The WFM client MUST populate the `adoptedManifestVersion` attribute with the `manifestVersion` of the most recent state manifest it has adopted for the reported deployment. A reported version `N` means the client has taken up the deployment as manifest `N` defined it. The reported version MUST match the revision of the deployment the client holds. A client still on an older revision reports that older version.
+
+Fetching a newer state manifest does not by itself advance the reported version for a deployment. Until the client begins applying the deployment's newer revision, it keeps reporting the version of the revision it still holds. The reported version need not be the version at which the deployment last changed. A client that has lost its local state and resynchronized reports the version it resynchronized against, which can be later.
+
+The attribute is present in every status report. A client learns of a deployment from a versioned state manifest, so it always has a version to report for a deployment it has taken up. On a first install the client reports the version of the manifest it adopted the deployment from, even if applying it fails. There is no reserved value for "no previous version".
+
+> Note: Manifest versions increase monotonically and never repeat, so the WFM can order any reported version against the versions it has published, even when a deployment's content reverts to an earlier revision.
+
 ## Example Deployment Status Manifest Request
 
 ```json
 {
     "deploymentId": "a3e2f5dc-912e-494f-8395-52cf3769bc06",
     "deviceId": "plant-alfa-zone1-edge01",
+    "adoptedManifestVersion": 7,
     "status": {
         "state": "pending",
         "error": {

@@ -530,12 +530,14 @@ components:
 
     DeploymentStatusManifest:
       type: object
-      required: [deploymentId, status, components]
+      required: [deploymentId, adoptedManifestVersion, status, components]
       properties:
         deploymentId:
           type: string
         deviceId:
           $ref: '#/components/schemas/DeviceId'
+        adoptedManifestVersion:
+          $ref: '#/components/schemas/ManifestVersion'
         status:
           type: object
           required: [state]