feat(cutover): orchestrate cash wallet migration with client-aware presentation

dev/apollo-federation/supergraph.graphql

@@ -501,6 +501,29 @@ type CashoutOffer
   walletId: WalletId!
 }
 
+type CashWalletCutover
+  @join__type(graph: PUBLIC)
+{
+  completedAt: Timestamp
+  cutoverVersion: Int!
+  pauseReason: String
+  pausedAt: Timestamp
+  runId: String
+  scheduledAt: Timestamp
+  startedAt: Timestamp
+  state: CashWalletCutoverState!
+  updatedAt: Timestamp!
+  updatedBy: String
+}
+
+enum CashWalletCutoverState
+  @join__type(graph: PUBLIC)
+{
+  COMPLETE @join__enumValue(graph: PUBLIC)
+  IN_PROGRESS @join__enumValue(graph: PUBLIC)
+  PRE @join__enumValue(graph: PUBLIC)
+}
+
 """(Positive) Cent amount (1/100 of a dollar)"""
 scalar CentAmount
   @join__type(graph: PUBLIC)
@@ -1651,6 +1674,7 @@ type Query
   btcPrice(currency: DisplayCurrency! = "USD"): Price @deprecated(reason: "Deprecated in favor of realtimePrice")
   btcPriceList(range: PriceGraphRange!): [PricePoint]
   businessMapMarkers: [MapMarker!]!
+  cashWalletCutover: CashWalletCutover!
   currencyList: [Currency!]!
   globals: Globals
   isFlashNpub(input: IsFlashNpubInput!): IsFlashNpubPayload

dev/bruno/Flash GraphQL API/admin/cash-wallet-cutover/01-query-admin-state.bru

@@ -0,0 +1,48 @@
+meta {
+  name: 01-query-admin-state
+  type: graphql
+  seq: 1
+}
+
+post {
+  url: {{admin_url}}
+  body: graphql
+  auth: bearer
+}
+
+auth:bearer {
+  token: {{admin_token}}
+}
+
+body:graphql {
+  query CashWalletCutoverAdminState {
+    cashWalletCutover {
+      state
+      scheduledAt
+      startedAt
+      completedAt
+      pausedAt
+      pauseReason
+      cutoverVersion
+      runId
+      updatedBy
+      updatedAt
+    }
+  }
+}
+
+body:graphql:vars {
+  {}
+}
+
+script:post-response {
+  test("admin cutover state returns without GraphQL errors", function () {
+    const jsonData = res.getBody()
+    expect(jsonData.errors).to.be.undefined
+    expect(jsonData.data.cashWalletCutover.state).to.be.oneOf([
+      "PRE",
+      "IN_PROGRESS",
+      "COMPLETE",
+    ])
+  })
+}

dev/bruno/Flash GraphQL API/admin/cash-wallet-cutover/02-set-scheduled-pre.bru

@@ -0,0 +1,61 @@
+meta {
+  name: 02-set-scheduled-pre
+  type: graphql
+  seq: 2
+}
+
+post {
+  url: {{admin_url}}
+  body: graphql
+  auth: bearer
+}
+
+auth:bearer {
+  token: {{admin_token}}
+}
+
+body:graphql {
+  mutation CashWalletCutoverSetScheduledPre($input: CashWalletCutoverUpdateInput!) {
+    cashWalletCutoverUpdate(input: $input) {
+      errors {
+        message
+      }
+      cashWalletCutover {
+        state
+        scheduledAt
+        startedAt
+        completedAt
+        pauseReason
+        cutoverVersion
+        runId
+        updatedBy
+        updatedAt
+      }
+    }
+  }
+}
+
+body:graphql:vars {
+  {
+    "input": {
+      "state": "PRE",
+      "scheduledAt": "2026-05-22T15:00:00.000Z",
+      "cutoverVersion": 345,
+      "runId": "manual-eng-345",
+      "pauseReason": "manual ENG-345 preflight"
+    }
+  }
+}
+
+script:post-response {
+  test("sets cutover config to PRE with schedule metadata", function () {
+    const jsonData = res.getBody()
+    expect(jsonData.errors).to.be.undefined
+    expect(jsonData.data.cashWalletCutoverUpdate.errors).to.eql([])
+
+    const config = jsonData.data.cashWalletCutoverUpdate.cashWalletCutover
+    expect(config.state).to.eql("PRE")
+    expect(config.cutoverVersion).to.eql(345)
+    expect(config.runId).to.eql("manual-eng-345")
+  })
+}

dev/bruno/Flash GraphQL API/admin/cash-wallet-cutover/03-set-in-progress.bru

@@ -0,0 +1,60 @@
+meta {
+  name: 03-set-in-progress
+  type: graphql
+  seq: 3
+}
+
+post {
+  url: {{admin_url}}
+  body: graphql
+  auth: bearer
+}
+
+auth:bearer {
+  token: {{admin_token}}
+}
+
+body:graphql {
+  mutation CashWalletCutoverSetInProgress($input: CashWalletCutoverUpdateInput!) {
+    cashWalletCutoverUpdate(input: $input) {
+      errors {
+        message
+      }
+      cashWalletCutover {
+        state
+        scheduledAt
+        startedAt
+        completedAt
+        pauseReason
+        cutoverVersion
+        runId
+        updatedBy
+        updatedAt
+      }
+    }
+  }
+}
+
+body:graphql:vars {
+  {
+    "input": {
+      "state": "IN_PROGRESS",
+      "cutoverVersion": 345,
+      "runId": "manual-eng-345",
+      "pauseReason": "manual ENG-345 in-progress test"
+    }
+  }
+}
+
+script:post-response {
+  test("sets cutover config to IN_PROGRESS", function () {
+    const jsonData = res.getBody()
+    expect(jsonData.errors).to.be.undefined
+    expect(jsonData.data.cashWalletCutoverUpdate.errors).to.eql([])
+
+    const config = jsonData.data.cashWalletCutoverUpdate.cashWalletCutover
+    expect(config.state).to.eql("IN_PROGRESS")
+    expect(config.cutoverVersion).to.eql(345)
+    expect(config.runId).to.eql("manual-eng-345")
+  })
+}

dev/bruno/Flash GraphQL API/admin/cash-wallet-cutover/04-set-complete.bru

@@ -0,0 +1,60 @@
+meta {
+  name: 04-set-complete
+  type: graphql
+  seq: 4
+}
+
+post {
+  url: {{admin_url}}
+  body: graphql
+  auth: bearer
+}
+
+auth:bearer {
+  token: {{admin_token}}
+}
+
+body:graphql {
+  mutation CashWalletCutoverSetComplete($input: CashWalletCutoverUpdateInput!) {
+    cashWalletCutoverUpdate(input: $input) {
+      errors {
+        message
+      }
+      cashWalletCutover {
+        state
+        scheduledAt
+        startedAt
+        completedAt
+        pauseReason
+        cutoverVersion
+        runId
+        updatedBy
+        updatedAt
+      }
+    }
+  }
+}
+
+body:graphql:vars {
+  {
+    "input": {
+      "state": "COMPLETE",
+      "cutoverVersion": 345,
+      "runId": "manual-eng-345",
+      "pauseReason": "manual ENG-345 complete test"
+    }
+  }
+}
+
+script:post-response {
+  test("sets cutover config to COMPLETE", function () {
+    const jsonData = res.getBody()
+    expect(jsonData.errors).to.be.undefined
+    expect(jsonData.data.cashWalletCutoverUpdate.errors).to.eql([])
+
+    const config = jsonData.data.cashWalletCutoverUpdate.cashWalletCutover
+    expect(config.state).to.eql("COMPLETE")
+    expect(config.cutoverVersion).to.eql(345)
+    expect(config.runId).to.eql("manual-eng-345")
+  })
+}

dev/bruno/Flash GraphQL API/admin/cash-wallet-cutover/folder.bru

@@ -0,0 +1,4 @@
+meta {
+  name: cash-wallet-cutover
+  seq: 10
+}

dev/bruno/Flash GraphQL API/notoken/queries/cash-wallet-cutover.bru

@@ -0,0 +1,44 @@
+meta {
+  name: cash-wallet-cutover
+  type: graphql
+  seq: 11
+}
+
+post {
+  url: {{flashGraphqlUrl}}
+  body: graphql
+  auth: inherit
+}
+
+body:graphql {
+  query CashWalletCutoverPublicState {
+    cashWalletCutover {
+      state
+      scheduledAt
+      startedAt
+      completedAt
+      pausedAt
+      pauseReason
+      cutoverVersion
+      runId
+      updatedBy
+      updatedAt
+    }
+  }
+}
+
+body:graphql:vars {
+  {}
+}
+
+script:post-response {
+  test("public cutover state returns without GraphQL errors", function () {
+    const jsonData = res.getBody()
+    expect(jsonData.errors).to.be.undefined
+    expect(jsonData.data.cashWalletCutover.state).to.be.oneOf([
+      "PRE",
+      "IN_PROGRESS",
+      "COMPLETE",
+    ])
+  })
+}

operator-runs/eng-345-manual-347/findings.md

@@ -0,0 +1,6 @@
+# Findings
+
+- `preparePrimaryCashWalletCutover` accepts injected repositories, so the test can scope discovery to the 10 created accounts by passing an `accountsRepo.listUnlockedAccounts()` generator for only those IDs.
+- Account creation creates both USD and USDT checking wallets and defaults new accounts to USDT. For this test, each new account must be explicitly updated back to the USD wallet with `Accounts.updateDefaultWalletId`.
+- Funding can use `Payments.intraledgerPaymentSendWalletIdForUsdWallet` from the funder account's USD wallet to each target legacy USD wallet. The amount argument is cents, so `$0.25` is `25` and `$0.01` is `1`.
+- Cutover batch execution can use `CashWalletCutover.runPrimaryCashWalletCutoverBatch`; status and lifecycle can use the existing app lifecycle functions.