feat(contracts): add contract upgradeability plan + versioning tests (#1809)

[nissinanlung]

Summary

Closes #1809.

Storage/upgrade risks were unmanaged. This adds the authoritative upgradeability plan (versioning scheme, step-by-step migration flow, rollback/emergency procedures, blue-green cutover) plus real-contract tests for the subscription upgrade hooks.

Changes

• docs/CONTRACT_UPGRADE_PLAN.md — proxy+storage+implementation architecture; STORAGE_VERSION/ProxyVersion scheme; monotonic upgrade rules; step-by-step in-place upgrade procedure (schedule → timelock → validate → migrate → version bump); rollback & emergency procedures; blue-green cutover for breaking changes; version history table; test coverage mapping.
• contracts/subscription/tests/upgrade_versioning.rs — 7 tests against the real SubTrackrSubscription + UpgradeableProxy + SubTrackrStorage trio (no mocks):
  • get_version returns current STORAGE_VERSION
  • validate_upgrade accepts prior/current (1, 2), rejects 0 and future (3)
  • migrate is a no-op at current version; rejects unsupported future path
  • migrate_v1_to_v2_rebuilds_user_plan_index_for_active_only — drops UserPlanIndex to simulate a v1 snapshot, runs migrate(1), asserts the index is rebuilt for active subscriptions only (cancelled skipped)
  • proxy version tracks implementation version after initialize
  • Verified passing locally on stable cargo.

Acceptance criteria

• Versioning — STORAGE_VERSION constant + ProxyVersion proxy storage; monotonic upgrades enforced; per-version migrate arms.
• Migration steps — in-place schedule→timelock→validate→migrate→bump flow plus blue-green cutover for breaking changes; rollback path.
• Tested — upgrade_flow.rs (proxy lifecycle) + upgrade_versioning.rs (real-contract versioning, compatibility gates, v1→v2 migration).

Quality Gates

• Rust tests pass locally (cargo test --test upgrade_versioning, stable)
• Rust build / clippy (CI)
• Documentation updated

[drips-wave]

@nissinanlung Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits