Harden module update compatibility cleanup

docs/RELEASE_DEPENDENCIES.md

@@ -205,6 +205,12 @@ Each module entry can declare:
 - WebUI package name and pinned install reference
 - display metadata and tags
 - `license_features`, the feature entitlements required to plan that install
+- `dependencies` and `optional_dependencies`, the module ids expected in the
+  target module set
+- `migration_safety`, one of `automatic`, `requires_review`, `forward_only`,
+  or `destructive`
+- `migration_notes`, operator-facing data/migration guidance for review,
+  forward-only, or destructive changes
 - `provides_interfaces`, named interface contracts exported by this module
 - `requires_interfaces`, named interface contracts and version ranges required
   by this module
@@ -264,16 +270,22 @@ source/path, source type, cache path, channel, sequence, generated/validity
 timestamps, signature state, trusted key id, and cache state where available.
 Catalog provenance changes preflight severity:
 
-- catalog-sourced installs require a configured, valid package catalog before
-  activation
+- catalog-sourced installs and updates require a configured, valid package
+  catalog before activation
 - invalid, untrusted, expired, not-yet-valid, replayed, or unapproved-channel
-  catalogs block catalog-sourced installs
+  catalogs block catalog-sourced installs and updates
 - the same catalog validation failures remain warnings for manual install
   plans, so operators can still use offline or emergency package refs
 - valid-catalog warnings, such as intentionally unsigned local catalogs when
   signature enforcement is disabled, remain warnings
 - selected catalog entries with unsatisfied non-optional named interface ranges
   block activation before the installer runs
+- selected catalog entries whose target dependencies are neither installed nor
+  planned block activation before the installer runs
+- catalog entries marked `forward_only` or `destructive` block activation until
+  the plan row has an explicit data-safety acknowledgement
+- catalog entries marked `destructive` also require catalog migration notes or
+  operator notes describing the cleanup or retirement plan
 
 ### Update Paths
 
@@ -283,6 +295,16 @@ catalog validation snapshot. The installer may install multiple packages into
 the environment before activation, then validate the discovered manifests and
 activate the resulting set together.
 
+Install-plan rows support explicit `install`, `update`, and `uninstall`
+actions. Catalog planning writes `update` when the module is already installed.
+Preflight resolves the target set from installed manifests plus the planned
+catalog entries. Unplanned catalog entries are not treated as installed; when
+they would satisfy a missing dependency or named interface, preflight blocks
+activation with a companion-update issue so the operator can add them to the
+same plan. The preflight response also includes a structured `target_plan`
+summary with each planned module's action, current version, catalog target
+version, package refs, migration-safety level, and acknowledgement state.
+
 This avoids circular "upgrade A first / upgrade B first" traps: named interface
 requirements are solved against the target set, not against each intermediate
 package-install moment. If the target set cannot satisfy all non-optional
@@ -303,6 +325,15 @@ Live data upgrades need an even stricter rule:
   must publish an intermediate compatibility release rather than a circular
   update chain
 
+The release catalog is the first safety gate for this. Generated catalogs mark
+modules with registered migrations as `requires_review` by default. Release
+authors should keep that value for ordinary reversible migrations, raise it to
+`forward_only` when database rollback requires restoring a snapshot, and raise
+it to `destructive` when the update removes or irreversibly rewrites persisted
+data. The admin install-plan UI exposes the safety level and lets operators
+record an explicit acknowledgement; preflight keeps acknowledged
+forward-only/destructive changes visible as warnings.
+
 In practice, circular dependencies are avoided by designing interfaces with
 compatibility windows and by publishing bridge releases. A bridge release keeps
 the old interface while introducing the new one, allowing dependent modules to