Finalized proposal

design/decisions/0004-entity-dregister-api.md

@@ -28,7 +28,53 @@ the complete entity hierarchy that is associated with it.
   between the parent device and its child devices.
   And when custom topic schemes are used, even the device and its service may not have any common prefix available.
 
-## Solution Proposals
+## Finalized Solution Proposal
+
+Entities can be deregistered by clearing their registration message from the broker, publishing empty retained messages to their topic id, as follows:
+
+```sh
+tedge mqtt pub -r te/device/child01// ''
+```
+
+This message will result in the deregistration of that target entity and all the nested entities (services and child devices) linked to it.
+
+Different `tedge` components will react to the deregistration messages as follows:
+
+**tedge-agent**
+
+* The `tedge-agent` identifies the entire nested entity hierarchy of the target entity and issue clear messages for all of them, starting from the leaf nodes.
+* A parent entity must be cleared from the broker only after all its children are cleared, so that even if the agent crashes in the middle of a deregistration,
+  it can resume on restart.
+
+:::note
+To easily identify the target entity hierarchy to be deregistered, the `tedge-agent` also needs to maintain its own entity store, which it doesn't currently do.
+:::
+
+**tedge-mapper**
+
+* The `tedge-mapper` clears the entity metadata of the target entity and its children (services and child devices) from its own entity store.
+* Since deregistration messages for different entities could be received out of order, a child's clear message could be received after the parent is cleared.
+  In such cases, simply ignore the clear message for that non-existent entity.
+* Propagating the deregistration to the cloud (removing the managed object from the cloud) is controlled by the config setting: `c8y.sync.push_deregister_upstream`.
+* When the `c8y.sync.push_deregister_upstream` setting is set to `true`, the corresponding managed object is deleted from the cloud using the
+  [Delete managed object REST API](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource).
+  If the config setting value is `false`, the managed object in the cloud is left untouched.
+
+### Limitations
+
+This solution has the following limitations:
+
+1. There is no feedback available to the user when the deregistration of an entire device hierarchy is complete, especially the child entities.
+   Although the deregistration of the target entity itself can be validated by checking if its registration message is cleared from the broker,
+   the same can't be done for the child entities as there is no API currently available to query the list of all the children of an entity.
+1. No filtering capabilities available for more fine-grained deregistration (e.g: deregister only the services/children of a given entity).
+
+Both these limitations can be alleviated in future by introducing new commands that lets users register/deregister entities and even list them
+based on some filtering criteria.
+Since commands inherently supports status updates, the status of operations like `register` and `deregister` can also be published via the same.
+This command based approach is documented in one of the deferred proposals [here](#mqtt-api-3).
+
+## Appendix (Comparison of all the proposals)
 
 ### Using third-party MQTT tools like mosquitto_sub
 
@@ -142,10 +188,6 @@ tedge mqtt pub -r te/device/child01// ''
 
 ### MQTT API 3
 
-:::note
-Preferred solution
-:::
-
 Deregister using commands as follows:
 
 ```sh
@@ -200,11 +242,3 @@ The mappers must also react the same way to the clear commands.
 **Cons**
 
 * Inconsistency with the registration API which is available only via MQTT
-
-### Other Enhancements
-
-Here are a few other enhancements required, irrespective of the solution chosen:
-
-* The mappers, on receipt of an empty retained messages on an entity topic id, must remove that entity from its own entity store.
-* A tedge config setting, that allows the user to choose whether entity deregistrations must be propagated to the cloud or not.
-  Optionally, an additional command payload option can also be provided to control this at an individual request level.