Harden module update compatibility cleanup

docs/MODULE_ARCHITECTURE.md

@@ -489,11 +489,16 @@ does not trust the website by location alone. A catalog must pass the configured
 signature, channel, freshness, and replay rules before a catalog entry can be
 planned. Catalog entries may declare `license_features`; core checks those
 against the configured offline license before adding the entry to the install
-plan.
+plan. Catalog entries may also declare `migration_safety` as `automatic`,
+`requires_review`, `forward_only`, or `destructive`; forward-only and
+destructive entries require explicit operator acknowledgement in the install
+plan before installer preflight allows activation.
 
 Modules should provide:
 
 - pinned backend and WebUI package refs for official catalog entries
+- module dependency metadata for catalog target-state planning
+- migration-safety metadata for catalog update planning
 - compatibility metadata in the module manifest
 - named interface contracts in the manifest and catalog entry when the module
   provides or consumes cross-module APIs
@@ -977,8 +982,15 @@ The package install-plan API records operator intent only:
   also reports catalog validity, channel, signature, trust state, and the
   configured path.
 - `POST /api/v1/admin/system/modules/install-plan/catalog/{module_id}` saves
-  a planned install row from a validated catalog entry. Catalog signature and
-  approved-channel policy are enforced before the row is saved.
+  a planned install or update row from a validated catalog entry. Installed
+  modules are planned as updates. Catalog signature and approved-channel policy
+  are enforced before the row is saved. The saved plan row can also carry a
+  data-safety acknowledgement used by preflight for forward-only or destructive
+  catalog entries.
+- Install-plan preflight returns a structured `target_plan` summary so the
+  admin UI can show current version, target version, package refs,
+  migration-safety level, and acknowledgement state without requiring JSON
+  editing.
 - `POST /api/v1/admin/system/modules/{module_id}/uninstall-plan` saves a
   planned non-destructive uninstall row for an installed module after it has
   been disabled. The Python distribution name is resolved from the installed

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