feat: multi-hop contract WASM migration via legacy_contracts.toml

[sanity]

Problem

When Delta republishes with a new site_contract.wasm, every site's contract_key changes because contract_key = BLAKE3(BLAKE3(wasm) || params). Sites with a persisted KnownSiteRecord.contract_key_b58 migrate fine, but records restored from delegates older than b82d3bc have contract_key_b58 = None and were falling through to a hardcoded one-hop OLD_WASM_HASH constant. That constant had silently rotted across releases — pointing at 1188d108… (commit 2e664c3) while the actually-previous release shipped b92da83d… — so users of the previous release were stranded on a permanent "Loading..." screen after the V7 republish.

See also: 356e6b6 which updated OLD_WASM_HASH as an emergency hotfix. This PR replaces the single-constant mechanism with a proper multi-hop registry, on the same pattern as legacy_delegates.toml.

Approach

• legacy_contracts.toml — single source of truth for previous contract WASM hashes.
• ui/build.rs — parses it and emits LEGACY_CONTRACT_HASHES: &[[u8; 32]].
• contract_id_for_prefix_with_hash — pure, unit-tested function governing contract-key derivation for any (prefix, hash) pair.
• fire_legacy_contract_migrations — fires a migration GET for every historical hash at startup. Uses the existing PENDING_MIGRATIONS map to correlate responses.
• clear_pending_migrations_for_prefix — on successful migration, cancels other in-flight probes for that prefix so a slower response from an older hash can't race ahead and overwrite fresh state.
• restore_known_sites — now always issues current-key GET + stored-but-stale probe + generic legacy sweep. The NotFound handler no longer eagerly retries the current key on every legacy-probe miss.
• scripts/add-contract-migration.sh — mirrors scripts/add-migration.sh. Run before touching common/ or the contract.
• scripts/check-migration.sh — extended to enforce the contract-side recording. If the contract WASM changed since HEAD and the previous hash is not in legacy_contracts.toml, preflight fails loudly instead of silently stranding users.
• AGENTS.md — updated upgrade workflow.

Tests

• contract_id_is_deterministic_and_depends_on_both_hash_and_prefix
• legacy_ids_are_deduplicated_and_exclude_current
• legacy_contract_hashes_table_is_populated — guards against an empty generated file.

All existing tests continue to pass: delta-core 19/19, delta-ui 6/6, site-delegate 4/4.

Initial entries

• C1 = 1188d108… — pre-tombstone WASM (commit 2e664c3).
• C2 = b92da83d… — pre-V7 WASM (f5ecff5), where today's stranded users' state actually lives.

WASMs

Contract and delegate WASMs are byte-identical to main. This PR is pure UI logic + scripts + registry.

[AI-assisted - Claude]

[sanity]

Addressed review feedback in 02c5f5e (force-pushed after rebase onto main for the reproducible-WASM fix).

Code-first / Skeptical H1+H2+H3 (critical race): late-response overwrites.

Before, cancellation only removed entries from PENDING_MIGRATIONS. Any GET response already in flight when cancel fired would land in handle_contract_response's non-migration branch, call handle_site_state, and last-write-wins over the freshly-captured state. Confirmed real — traced by both reviewers.

Fix: introduced MIGRATING_PREFIXES set populated at startup per site, plus an explicit classify_get_response state machine that routes each incoming GET into one of four branches — PendingMigration, InitialCurrentKey, LiveUpdate, Unknown. Late responses for a prefix whose capture has completed are dropped from the migration write path but still work normally for steady-state UpdateNotification merging via the LiveUpdate branch. finalize_prefix_capture atomically removes the prefix from MIGRATING_PREFIXES AND clears all PENDING_MIGRATIONS entries for it, so siblings can't sneak through after cancellation.

Skeptical M2 (thundering herd): fire_legacy_contract_migrations now runs only when old_key_b58.is_none() || stored_key_is_stale. In the steady state where the delegate's stored key matches the current WASM, the site was created under the current contract and no earlier WASM could have state for it — the sweep was pure waste. Drops startup load from N × M GETs to just the stored-key GET for up-to-date sites.

Skeptical M4 (derivation symmetry): added contract_id_matches_state_key_derivation_for_current_wasm which computes the current WASM's BLAKE3 hash and asserts that contract_id_for_prefix_with_hash agrees with the production state::contract_key_from_prefix path. Guards against any future backwards-incompatible change to freenet-stdlib's ContractKey::from_params_and_code.

Test gap L1: extracted classify_get_response as a pure state machine and added 5 unit tests covering all branches, including the tiebreaker where a key is both in PENDING_MIGRATIONS and its prefix in MIGRATING_PREFIXES (pending must win so the migration PUT runs).

Code-first concern 6: add-contract-migration.sh now always hashes git show HEAD:ui/public/contracts/site_contract.wasm and warns if the working tree differs, so a developer who accidentally rebuilt before recording won't silently record the new hash.

Skeptical M3 (C1 ghost hash): verified historically — git show 2e664c3:ui/public/contracts/site_contract.wasm | b3sum produces 1188d108…, so C1 really did ship. Kept.

Rebase: picked up #4's reproducible-WASM fix. check-migration.sh now uses the new scripts/build-wasm.sh wrapper for both delegate and contract build-vs-committed verification. legacy_contracts.toml gains C3 = 53e3395f…, the V7 contract hash shipped immediately before reproducible builds landed — this is where the currently-stranded user's site state actually lives.

Not addressed (minor, deferred):

• Skeptical M1 (unbounded PENDING_MIGRATIONS on network silence): GET-timeout cleanup can be added as a follow-up; entries are bounded by N sites × M legacy hashes so not an immediate risk.
• Skeptical L6 (backup-state restore race with legacy-hash probes): same race surface as H1, now protected by the same MIGRATING_PREFIXES gate since handle_restored_site_state also routes through handle_site_state. Worth a follow-up to verify end-to-end.

Tests: delta-core 19/19, delta-ui 12/12, site-delegate 4/4. Clippy clean.

[AI-assisted - Claude]