feat(migration): add dry-run mode and rollback/recovery safeguards

[dev-fani]

How i resolved this issue

Contract upgrades are one of the riskiest operations this workspace performs. migration.rs and version_migration_helper.rs could validate that a version bump was forward-only, but there was no way to preview a migration without mutating state, no guard against skipping an entire major version, and no way to recover if a migration got stuck mid-flight. begin_migration even had its target-version parameter marked with // Reserved for wiring into validate_upgrade in a future change — it accepted a target version but never actually checked it (#11).

Approach

• validate_upgrade gains a force: bool parameter and now rejects both downgrades and version skips (jumping more than one MAJOR version, e.g. 1.x -> 3.x) unless force = true. This directly enforces the "migrate sequentially" / "skip versions not recommended" rule that was already written in VERSION_MIGRATION_POLICY.md but not enforced in code. Applied to both migration.rs's simpler MigrationHelper and version_migration_helper.rs's fuller EnhancedMigrationHelper, so the two files agree.
• begin_migration now actually validates its target version by calling validate_upgrade against the current stored version — closing the literal TODO comment that was in the code. A bad target is now rejected up front instead of only being caught later at complete_migration.
• New dry_run_migration: runs the same authorization, mutual-exclusion, and version-policy checks begin_migration would (plus any caller-supplied storage-layout errors/warnings, mirroring the existing validate_state shape), and returns a DryRunReport listing every problem found — without writing anything to storage.
• New cancel_migration: the actual recovery path when a migration is begun but never completes (the off-chain migration logic fails or crashes between begin_migration and complete_migration). Clears the stuck mutual-exclusion flag so a fresh migration can proceed. This replaces the previous "may need to manually clear flag if system crashed" non-solution in the docs with real, tested code.
• complete_migration gains a matching force: bool so a migration that was legitimately begun as a forced downgrade/skip isn't rejected again at completion.
• VERSION_MIGRATION_POLICY.md updated throughout: migration rules, the API reference for every changed/new function, the MigrationError list, the events list, the troubleshooting section, and a new "Recovering From a Partial Migration" walkthrough — so the documented policy matches what the code now enforces, per the issue's explicit ask.

Scope note: migration.rs's MigrationHelper isn't wired into any contract entry point and had zero test coverage before this change, so I added a small test module for it (forward/downgrade/skip/force cases plus its version/history storage helpers) rather than leaving the two files' behavior inconsistent.

How this was tested

• soroban/tests/version_migration_tests.rs: updated all existing call sites for the new signatures, and added coverage for — a valid forward migration, version-skip rejected and allowed-when-forced (both at validate_upgrade and begin_migration level), downgrade rejected and allowed-when-forced, a dry-run that reports issues without mutating version/history/in-progress state, dry-run reporting an unauthorized caller plus caller-supplied storage errors together, and cancel_migration unsticking a stuck migration (plus its own unauthorized/nothing-to-cancel error cases).
• soroban/src/migration.rs: new inline test module covering the same forward/downgrade/skip/force matrix plus version get/set and history round-trips.
• Full CI checklist run locally:
  • cargo fmt --all -- --check — pass
  • cargo clippy --all-targets --all-features -- -D warnings — pass
  • cargo build --release --target wasm32-unknown-unknown — pass
  • cargo test (full workspace) — 517 lib tests + 30 migration integration tests (up from 506 and 19), 0 failed

Closes #11