# V2 → V3 migration and rollback runbook

## Non-negotiable preservation rules

1. V2 contracts, V2 withdrawal paths, V2 route paths, V2 ABIs, and V2 historical reads remain intact.
2. V2 is the default for all writes until an explicit version selection is made; no client, API, or agent may silently redirect a V2 write to V3.
3. Migration is voluntary and consists of independent user actions. It is not a contract upgrade or asset transfer from V2 to V3.
4. A V3 pause or rollback must preserve V3 principal withdrawal/refund paths where the implementation’s approved invariant requires it. It must never impair V2 withdrawals/routes.

## Preconditions — all must be evidenced

- BB-01 through BB-05 have the required evidence for the intended scope.
- V2 withdrawal and route regression results are current and independently reviewed.
- The V3 manifest has verified target addresses, code hashes, ABI/version, ownership/governance state, and `pilotReady` is changed only by an approved release process.
- The cap/maximum-loss decision is approved for the exact asset/module/route, and the post-change maximum loss is bounded.
- The independent audit handoff is frozen; the result and unresolved findings are linked.
- A rollback rehearsal proves V2 routes and withdrawals remain available.

## Migration procedure (per user and position)

1. Present an explicit version selector with **V2 preselected**. Explain that V3 is separate and may have distinct risk/caps.
2. Record a read-only V2 position snapshot (chain, contract, position identifier, block/finality, asset amount where applicable). Do not treat an RPC failure as zero.
3. The user independently uses the existing V2 withdrawal/deactivation route to their wallet. Confirm finality and retain the receipt/reference.
4. Verify the V2 withdrawal result against the snapshot. If it fails or is incomplete, stop; do not create a V3 position.
5. Only after a separate, explicit V3 choice and all V3 gates are met may the user fund/create the V3 position. Do not couple V2 withdrawal and V3 funding in a hidden route.
6. Record a V3 receipt/reference and post-state read. Link it to the V2 record only as off-chain migration metadata; do not publish PII.
7. Reconcile: V2 retained/withdrawn position plus user-funded V3 amount must match the approved accounting model. Any discrepancy blocks further migration.

## Rollback / incident procedure

| Trigger | Immediate action | V2 preservation check | V3 containment |
|---|---|---|---|
| V3 route/API regression | Disable only the V3 route/feature exposure; preserve V2 route responses and schemas | Query V2 route and withdrawal path at finality | No automatic reverse transaction; stop new V3 requests. |
| V3 module defect or invariant failure | Stop new V3 enrollment/factory permissions for affected scope | Run V2 withdrawal and route regression set | Apply only approved V3 pause/containment that preserves withdrawals/refunds. |
| Cap/loss threshold breach or monitoring gap | Stop affected V3 write path; preserve evidence | Confirm V2 default remains in UI/SDK/agent configuration | Do not increase caps or activate another route to compensate. |
| Migration reconciliation discrepancy | Stop the affected user flow and investigate | Verify V2 user position/receipt remains unchanged by the investigation | Do not retry by auto-funding, replaying, or moving funds. |
| Governance evidence mismatch | Treat proposal as invalid; do not execute | Verify no V2 administrative call was included | Rebuild a single-action proposal after review. |

## Exit / restore criteria

Resume only after the defect’s scope is fixed, the frozen source/build reference changes are reviewed, V2 preservation tests pass, affected V3 withdrawal/refund behavior is verified, the cap decision is revisited, and an independent reviewer records approval for the exact resumed action. No rollback condition authorizes a V2 route change.
