Skip to main content

ADR-007: Wallet Topology And Policy Atomic Activation

Status​

Accepted

Date​

2026-04-27

Owners​

  • Platform Backend
  • Wallet Domain

Affected Services​

  • wallet_service
  • admin_service
  • game_service
  • rolling_service
  • promotion_service
  • gateway
  • docs/specs/wallet/2026-04-23-ruby-wallet-split-structure.md
  • docs/services/wallet-service.md
  • docs/runbooks/wallet/ruby-wallet-topology-rollout.md
  • docs/adr/ADR-005-wallet-topology-bucket-ledger-model.md

Context​

Wallet topology defines bucket shape, while wallet policy defines how those buckets are used. Activating one without the other can strand wallet commands: the active topology may have no matching active policy, or a policy may point to a topology that is not active.

Topology switches such as split to unified cannot safely be done by first activating a policy and then activating a topology because only one policy per policy key may be ACTIVE.

Decision​

Topology switches must activate the topology and matching policy in one wallet service transaction.

The management route accepts policy_document alongside an activated topology document and calls the atomic activation path. Direct policy activation remains allowed only when the policy targets the currently active topology.

Before activation, wallet service validates:

  • topology document structure
  • policy topology code and version
  • every provider funding rule
  • selected-source references
  • normal-wallet settlement destinations
  • points transfer targets
  • active transfer edges
  • live-state reachability and immutable bucket semantics

Consequences​

Positive:

  • no production window exists where active topology and active policy are mismatched
  • split-to-unified and future wallet-shape changes have one operational action
  • invalid settlement or points targets are rejected before money movement

Negative:

  • BO editors must submit topology and policy together for shape-changing activation
  • rollout tooling must treat topology and policy as one deployment unit

Constraints​

  • Draft saves may not overwrite ACTIVE or SUPERSEDED topology or policy versions.
  • Direct topology activation without a policy document is only for the same topology/version with an already active matching policy.
  • Activation must fail when balances, active coupon grants, unsettled bets, or active rollings reference missing or semantically changed bucket codes.

Follow-Up​

  • Keep wallet topology route tests as contract tests for BO integration.
  • Add a BO UI guard that requires a policy document when activating a new topology version.