feat(storage): freeze storage key formats for upgrades (#1377)

[s6pa1rta3n-lab]

Summary

Freezes storage key formats, specifies discriminant allocations for DataKey variants, documents all key family encodings, and provides automated collision and migration verification to ensure safe contract upgrades.

Closes #1377

Acceptance Criteria Checklist

• Every key family has a documented encoding: Documented all 6 primary key families (Symbol Singletons, Formatted Symbols, Tuple Keys, Composite Vector Keys, Market ID Keys, and DataKey Enum variants 0..31) in docs/contracts/STORAGE_LAYOUT.md.
• Populated upgrade fixtures load without loss: Verified that populated upgrade fixtures containing markets, user balances, storage configuration, and claim nonces survive upgrades and round-trips without data loss (test_populated_upgrade_fixtures_load_without_loss).
• New keys cannot collide: Implemented pairwise O(n^2) collision testing over all 32 DataKey XDR encodings in unit and integration test suites (test_all_datakey_variants_have_unique_xdr, tests/datakey_collision.rs), and validated cross-family storage key isolation (test_cross_family_key_isolation).
• Migration tests cover empty, populated, and malformed state:
  • test_migration_empty_state: Empty unpopulated storage format migration across versions.
  • test_migration_populated_state: Sequential V1->V2 and V2->V3 migration with live market state.
  • test_migration_malformed_and_unsupported_state: Verifies unsupported downgrade paths and invalid/missing market integrity detection.

Changes

• docs/contracts/STORAGE_LAYOUT.md: Added section Frozen Storage Key Format (v1.0 Upgrade Specification) detailing key families, the frozen 32-variant DataKey registry, upgrade immutability rules, and migration invariants.
• contracts/predictify-hybrid/src/storage_layout_tests.rs: Added comprehensive tests covering pairwise XDR collision prevention across all 32 variants, cross-family key isolation, populated upgrade fixture preservation, and empty/populated/malformed state migrations.
• contracts/predictify-hybrid/tests/datakey_collision.rs: Enabled and expanded the integration collision detection test suite to validate pairwise uniqueness across all 32 DataKey variants.

Verification

• cargo test -p predictify-hybrid --lib storage_layout_tests (39 tests passed)
• cargo test -p predictify-hybrid --test datakey_collision (1 test passed)

Payout Routing

• EVM (Base/Arbitrum/Polygon/ETH): 0xF46C9F6d70C50BF81ef3588AB523a90a594a2F89
• Stellar: GCL6OXAMLD75BMTINA6EMRUDWK5THQUSHMYNLSNBCJAPZJHNYJTUNIBC