Document the schema-versioning and migration model for redeployments

[mikewheeleer]

Document SchemaVersion, version(), and the migration workflow

Description

contracts/escrow/src/lib.rs distinguishes the compiled version() (returns 2) from the persisted SchemaVersion (get_schema_version, defaulting to 1) and exposes migrate_v1_to_v2, but the relationship and the operational workflow are documented only in scattered /// comments. Operators have no guide for when and how to migrate. This issue captures the model.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add docs/escrow/migrations.md explaining: the difference between code version() and SchemaVersion; why v2 reads default sensibly for absent slots; how the MigrationVersionMismatch (#11) guard prevents double-runs.
• Provide a step-by-step migration runbook (deploy/redeploy → migrate_v1_to_v2 → verify get_schema_version).
• Note the forward path for future migrate_v2_to_v3-style functions and the append-only versioning convention.
• Link the doc from README.md.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/contracts-28-migration-docs
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — only /// clarifications if needed.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — optionally a doc-aligned migration assertion.
  • Add documentation: add docs/escrow/migrations.md; link from README.md.
  • Include NatSpec-style doc comments (///) where gaps are found.
  • Validate security: migration cannot be run by non-admin (documented and cross-checked).
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: documenting the double-run guard behaviour accurately.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

docs: document schema-versioning and migration workflow

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.