hydration data obliteration (#923)

- Feature: Hub obliterate operation deletes all local and backend hydration data for a module
- Improvement: Hub dashboard adds obliterate button for individual, bulk, and by-name module deletion

1 files changed, 18 insertions, 5 deletions

diff --git a/docs/hub.md b/docs/hub.md
index 52a6fa3be..78d05f9b9 100644
--- a/docs/hub.md
+++ b/docs/hub.md
@@ -30,18 +30,23 @@ stateDiagram-v2
     Provisioning --> Unprovisioned : failed
     Provisioned --> Hibernating : Hibernate
     Provisioned --> Deprovisioning : Deprovision / timeout
+    Provisioned --> Obliterating : Obliterate
     Provisioned --> Crashed : process exited
     Hibernating --> Hibernated : stopped
     Hibernating --> Provisioned : failed
     Hibernated --> Waking : Wake
     Hibernated --> Deprovisioning : Deprovision / timeout
+    Hibernated --> Obliterating : Obliterate
     Waking --> Provisioned : ready
     Waking --> Hibernated : failed
     Deprovisioning --> Unprovisioned : done
     Crashed --> Recovering : watchdog
     Crashed --> Deprovisioning : Deprovision
+    Crashed --> Obliterating : Obliterate
     Recovering --> Provisioned : success
     Recovering --> Unprovisioned : failed
+    Obliterating --> Unprovisioned : done
+    Obliterating --> Crashed : failed
 ```
 
 **Stable states:**
@@ -56,9 +61,9 @@ stateDiagram-v2
 - **Crashed** - process exited unexpectedly. The watchdog attempts an in-place restart
   automatically.
 
-Transitioning states (`Provisioning`, `Hibernating`, `Waking`, `Deprovisioning`, `Recovering`)
-are transient and held exclusively by one operation at a time. If hibernation fails (the
-process cannot be stopped cleanly), the instance remains Provisioned.
+Transitioning states (`Provisioning`, `Hibernating`, `Waking`, `Deprovisioning`, `Recovering`,
+`Obliterating`) are transient and held exclusively by one operation at a time. If hibernation
+fails (the process cannot be stopped cleanly), the instance remains Provisioned.
 
 **Hibernation vs deprovision:** hibernating stops the process but keeps the data directory
 intact, allowing fast restart on the next Wake. Deprovisioning triggers a GC cycle, then
@@ -66,9 +71,17 @@ dehydrates the instance's state back to the configured backend, then deletes all
 instance data. Explicit deprovision requests are always honoured; the watchdog timeout path
 always deprovisions rather than hibernates.
 
+**Obliterate vs deprovision:** deprovisioning preserves data on the hydration backend so the
+next provision of the same module starts warm. Obliterate permanently destroys both local
+instance data and all backend hydration data for the module. This is irreversible. Obliterate
+can be called on Provisioned, Hibernated, or Crashed instances. It also works on modules that
+are not currently tracked by the hub (already deprovisioned) -- in that case it deletes only
+the backend hydration data. Obliterating a module that was never provisioned is a no-op
+success.
+
 **Idempotent operations:** hibernating an already-hibernated instance, waking an
-already-provisioned instance, or deprovisioning a non-existent module all return success
-without side effects.
+already-provisioned instance, deprovisioning a non-existent module, or obliterating a
+never-provisioned module all return success without side effects.
 
 ## The Watchdog