Add differential upgrade compatibility gate

[devchant]

Problem

A successful WASM upload or compilation does not prove that a contract upgrade preserves live storage interpretation, authorization decisions, error behavior, event contracts, or accounting invariants. The existing execution path checked only the proposal hash, admin authorization, and cooldown before replacing the WASM.

Closes: Hub-of-Evolution#1008

Solution

This PR adds a fail-closed compatibility gate at the irreversible upgrade boundary.

• Adds UpgradeCompatibilityManifest, keyed by the exact proposed WASM hash.
• Adds UpgradeStateSnapshot and get_upgrade_state_commitment for deterministic representative-state commitments covering contract version, escrow count, recurring escrow allocation, signer threshold, paused state, and onboarding configuration.
• Adds submit_upgrade_compatibility_manifest and get_upgrade_compatibility_manifest.
• Requires source/target versions, non-zero commitments for state, interface, authorization, migration preconditions/postconditions, rollback limitations, and a migration checkpoint.
• Rejects stale versions, missing evidence, incomplete migrations, and records requiring manual handling before update_current_contract_wasm is called.
• Records state and migration commitments in UpgradeHistory and removes the manifest only after successful version/history updates.
• Keeps the existing proposal and approval entry points source-compatible; the new requirement is enforced at execution.
• Documents isolated old/new differential testing, resumable checkpoint submission, idempotent retries, and manual-record handling in the migration runbook.

Files Changed

• craft-nexus-contract/src/lib.rs: compatibility types, storage key, snapshot/manifest APIs, execution gate, error codes, and audit metadata.
• craft-nexus-contract/src/test.rs: missing-manifest rejection and successful manifest consumption/history assertions.
• craft-nexus-contract/docs/versioned-state-migration.md: operator workflow and CI/release expectations.

Technical Decisions

The manifest is stored separately from WasmUpgradeProposal to preserve compatibility with existing proposal records and callers. The chain validates the manifest against the current version and live snapshot commitment, while isolated tooling remains responsible for running the old/new artifacts and producing interface, authorization, invariant, event, and error evidence. A non-zero checkpoint and explicit manual_records == 0 make incomplete migration handling visible and fail closed.

Validation

• VS Code diagnostics: no errors in the touched Rust files.
• git diff --check: passed.
• Rust tests, type checking, linting, and production WASM build: not runnable in this container because cargo, rustc, and rustup are not installed. The repository commands are documented in craft-nexus-contract/scripts/test.sh and craft-nexus-contract/scripts/build.sh.
• No screenshots apply; this is a contract and migration tooling change.

Limitations and Follow-up

The on-chain contract cannot execute two WASM artifacts in an isolated simulation. The manifest therefore commits the results of external differential tooling rather than attempting to reproduce that environment on-chain. CI should wire the differential fixture/invariant runner to fail artifact publication when those commitments are not produced. Existing legacy records still require the migration runner to generate truthful commitments; the contract intentionally does not infer compatibility from storage shape alone.

No issue number was supplied with the request, so no issue-closing tag is included.

Closes Hub-of-Evolution#1008