feat(cutover): rollback handlers, reverse payment path, and admin surface (ENG-401)

dev/apollo-federation/supergraph.graphql

@@ -619,6 +619,7 @@ enum CashWalletCutoverState
   COMPLETE @join__enumValue(graph: PUBLIC)
   IN_PROGRESS @join__enumValue(graph: PUBLIC)
   PRE @join__enumValue(graph: PUBLIC)
+  ROLLED_BACK @join__enumValue(graph: PUBLIC)
 }
 
 """(Positive) Cent amount (1/100 of a dollar)"""

src/app/cash-wallet-cutover/amount-conversion.ts

@@ -53,6 +53,29 @@ export const usdtMicrosToUsdCentsCeil = (
   return ((parsed + USDT_MICROS_PER_USD_CENT - 1n) / USDT_MICROS_PER_USD_CENT).toString()
 }
 
+// Rollback (ENG-401): how much USD (expressed in USDT micros so it can be
+// paid with a sender-side USDT amount) the legacy wallet is still missing
+// versus the balance the account originally migrated with. Both inputs are
+// precise-cent decimal strings (up to 6 decimal places, as produced by
+// ibexUsdDollarsToPreciseCents).
+export const legacyShortfallUsdtMicros = ({
+  sourceUsdCents,
+  currentUsdCents,
+}: {
+  sourceUsdCents: string
+  currentUsdCents: string
+}): string | InvalidCashWalletCutoverAmountError => {
+  const source = usdCentsToUsdtMicros(sourceUsdCents)
+  if (source instanceof Error) return source
+  const current = usdCentsToUsdtMicros(currentUsdCents)
+  if (current instanceof Error) return current
+
+  const sourceMicros = BigInt(source)
+  const currentMicros = BigInt(current)
+  if (currentMicros >= sourceMicros) return "0"
+  return (sourceMicros - currentMicros).toString()
+}
+
 export const destinationShortfallUsdtMicros = ({
   targetUsdtMicros,
   startingUsdtMicros,

src/app/cash-wallet-cutover/guard.ts

@@ -36,7 +36,36 @@ export const evaluateCashWalletCutoverGuard = ({
   migration?: CashWalletMigration | null
 }): { route: CashWalletCutoverRoute } | ApplicationError => {
   if (cutover.state === "pre") return { route: "legacy_usd" }
-  if (cutover.state === "complete") return { route: "usdt" }
+
+  if (cutover.state === "complete") {
+    // Single-account rollback can occur after global complete (ENG-364 mode
+    // 3D): those accounts' funds are back on the legacy USD wallet and must
+    // not be blanket-routed to USDT.
+    if (migration?.status === "rollback_started") {
+      return new CashWalletCutoverInProgressError()
+    }
+    if (migration?.status === "rolled_back") return { route: "legacy_usd" }
+    return { route: "usdt" }
+  }
+
+  if (cutover.state === "rolled_back") {
+    // Run-level rollback completion requires every migration to be
+    // rolled_back or skipped_already_migrated (completePrimaryCashWalletRollback
+    // enforces this), so route by where funds actually sit and fail closed
+    // on anything inconsistent with a rolled-back run.
+    if (
+      !migration ||
+      migration.status === "not_started" ||
+      migration.status === "rolled_back"
+    ) {
+      return { route: "legacy_usd" }
+    }
+    if (migration.status === "skipped_already_migrated") return { route: "usdt" }
+    if (migration.status === "rollback_started") {
+      return new CashWalletCutoverInProgressError()
+    }
+    return new CashWalletMigrationFailedError()
+  }
 
   if (!migration || migration.status === "not_started") return { route: "legacy_usd" }
   if (

src/app/cash-wallet-cutover/index.ts

@@ -18,6 +18,8 @@ export * from "./executor"
 export * from "./runner"
 export * from "./handlers"
 export * from "./runtime-services"
+export * from "./rollback-worker"
+export * from "./rollback"
 export * from "./orchestrator"
 export * from "./lifecycle"
 export * from "./preview"

src/app/cash-wallet-cutover/index.types.d.ts

@@ -1,4 +1,4 @@
-type CashWalletCutoverState = "pre" | "in_progress" | "complete"
+type CashWalletCutoverState = "pre" | "in_progress" | "complete" | "rolled_back"
 
 type CashWalletMigrationStatus =
   | "not_started"
@@ -64,4 +64,20 @@ type CashWalletMigration = {
   startedAt?: Date
   completedAt?: Date
   updatedAt: Date
+  // Rollback (ENG-401). Progress inside `rollback_started` is field-driven —
+  // each sub-step records its artifact and is skipped on resume, mirroring
+  // how the forward pipeline guards on field presence.
+  rollbackRequestedAt?: Date
+  rollbackRequestedBy?: string
+  rollbackReason?: string
+  rollbackFromStatus?: CashWalletMigrationStatus
+  rollbackPointerRestoredAt?: Date
+  rollbackInvoicePaymentRequest?: string
+  rollbackInvoicePaymentHash?: string
+  rollbackPaymentTransactionId?: string
+  rollbackShortfallUsdtMicros?: string
+  rollbackShortfallInvoicePaymentRequest?: string
+  rollbackShortfallInvoicePaymentHash?: string
+  rollbackShortfallPaymentTransactionId?: string
+  rolledBackAt?: Date
 }