# Refute Production Migration and Launch Runbook

Every mutation command must first be run without its apply flag. Store manifests outside the public web root, record their SHA-256 hashes, and retain an encrypted database backup. Never manually edit a balance to resolve a variance.

## 1. Prepare identities and source snapshots (30A–30D)

1. Export the canonical Core identity catalog and link verified Invest/Folex users. Resolve duplicate email/phone conflicts manually; do not guess.
2. Run `refute:legacy-wallets` in Invest without `--apply`; resolve invalid identities and negative/invalid source balances. Apply, then run `--reconcile`.
3. Run `refute:folex-balances` without `--apply`; review every live account. Freeze funding briefly, run with `--apply --ack-source-frozen`, then run `--reconcile`.
4. Run `refute:wallet-migration --dry-run` in Core. Apply only the exact signed manifest with `--apply=/absolute/path/manifest.json --ack-source-frozen`. The command is resumable and does not change `wallets.balance`.

## 2. Reconcile staging (30E)

Run all component audits followed by `refute:reconcile-daily --date=YYYY-MM-DD --json`. The launch gate accepts only the latest report with `status=balanced` and `issue_count=0`.

Create an evidence JSON file containing:

```json
{
  "reconciliation_run_uuid": "UUID",
  "identity_manifest_hash": "SHA256",
  "invest_migration_hash": "SHA256",
  "folex_migration_hash": "SHA256",
  "localcoin_migration_hash": "SHA256"
}
```

## 3. Controlled pilots (30F–30G)

```bash
php artisan refute:launch begin --admin=ADMIN_ID
php artisan refute:launch advance --state=staging_reconciled --admin=ADMIN_ID --evidence=/secure/staging.json --ack-production-risk
php artisan refute:launch add-pilot --type=account --user=REFUTE_UUID --admin=ADMIN_ID
php artisan refute:launch advance --state=pilot --admin=ADMIN_ID --evidence=/secure/pilot-start.json --ack-production-risk
php artisan refute:launch add-pilot --type=merchant --user=MERCHANT_REFUTE_UUID --admin=ADMIN_ID
php artisan refute:launch advance --state=cutover_ready --admin=ADMIN_ID --evidence=/secure/merchant-signoff.json --ack-production-risk
```

While `REFUTE_LAUNCH_PILOT_ONLY=true`, the new Invest P2P API rejects users outside the approved pilot allow-list.

## 4. Production cutover (30H)

Freeze legacy mutations, drain queues/recovery cases, run reconciliation again, and obtain operational/security/business sign-off. Advance to `production` using evidence containing `pilot_signoff`. Monitor balances, escrow, custody, callbacks, error rates, and recovery queues. Roll back feature flags—not ledger journals—if acceptance thresholds fail.

## 5. Read-only and retirement (30I–30J)

Set `REFUTE_LEGACY_WALLETS_READ_ONLY=true`, deploy, reconcile, and then advance with evidence containing `cutover_reconciliation`. Invest legacy wallet mutations and LocalCoin wallet balance updates will be rejected.

After the retention window and final backup:

```dotenv
REFUTE_LEGACY_WALLETS_READ_ONLY=true
REFUTE_LEGACY_BALANCE_ENGINES_ENABLED=false
REFUTE_CORE_LEGACY_ROUTES=false
```

Advance to `legacy_retired` using evidence containing `retirement_backup`. The gate refuses retirement unless all three safeguards are set. Remove legacy code only in a subsequent reviewed deployment; preserve immutable migrations, journals, receipts, launch events, and backups.