schema-versioned migration/upgrade path for pool storage

[mikewheeleer]

Summary

There is no safe way to evolve pool storage — an upgrade risks reading stale layouts. Add a schema-version field and a guarded migration entrypoint.

Why this matters

Storage evolution without versioning corrupts state on upgrade. A version gate + migration makes upgrades safe and idempotent.

Requirements

• Store a schema_version; expose it via a read view.
• Add an admin-guarded migrate() that upgrades in-place, gated on the current version.
• Migration is idempotent — running it twice is a no-op.
• Emit an event recording the version transition.

Technical guidance

• Refuse to migrate from an unexpected version.
• Keep pre/post invariants asserted in tests.

Edge cases — each must have a test

• migrate from old version -> upgrades, version bumped
• migrate again -> no-op
• migrate from wrong version -> rejected
• non-admin migrate -> rejected
• post-migration invariants hold

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Automatic on-read migration
• Downgrade path

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.

[BigGoodness]

I’ve reviewed the issue and I’m interested in working on it. I’ll first inspect the existing CDN invalidation and virus scanning flow, identify where the results are currently handled, and implement persistent storage following the project’s existing patterns. I’ll also add the necessary tests and make sure the changes are properly integrated without breaking the current flow. I can submit a PR with the implementation and tests within three fours.

[Hillzo]

Hi maintainer, I'd like to work on this issue. I'll add a schema_version: u32 field to pool storage with a get_schema_version read view, then implement an admin-guarded migrate() that reads the current version, checks it against the expected pre-migration version (rejecting with a typed UnexpectedSchemaVersion { current: u32 } error otherwise), applies the layout changes, and writes the new version back in the same invocation. To make it idempotent, I'll have migrate() short-circuit as a no-op (no error, no event) whenever schema_version already equals the target version, so calling it twice is safe. I'll gate the call behind the existing admin auth check and return a typed Unauthorized error for non-admin callers, and emit a schema_migrated event with the from/to versions on an actual transition.

For tests I'll cover: migrating from the old version bumps the version and applies the expected storage shape; calling migrate() again is a no-op with no duplicate event; migrating from an unexpected version is rejected with UnexpectedSchemaVersion; a non-admin caller is rejected with Unauthorized; and post-migration invariants (e.g. balances/fields intact, version view matches storage) hold via assertions in both the migration test and a follow-up integration test. I'll run cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test locally before opening the PR, and the PR description will explain the approach

[mikewheeleer]

@Hillzo, good luck on the pool storage migration. Please read the full issue carefully and begin by confirming the existing storage layout and authorization conventions. Your implementation and PR need to cover the schema version gate, admin protection, safe handling of unexpected versions, idempotent re-entry, migration events, state preservation, and every test case requested in the description. Aim for a clean, reviewable, high-quality contract change, run the Rust checks, and reference Closes #460. Please open the PR within 48 hours of assignment or I will remove the assignment.

[grantfox-oss]

🦊 GrantFox — @Hillzo has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #460)
2. Your PR will be reviewed by the StableRoute-Org maintainers

Good luck! Track your progress on GrantFox.