feat(accounts): capability state machine + headline status nomenclature (ENG-516)

[islandbitcoin]

Summary

Backend half of ENG-516 (Account Upgrade Revamp). Retires Pro and International as user-facing tiers, renames Merchant → Business, and models the account as a set of capability flags from which the internal level is derived. Companion frappe-flash-admin PR adopts the new names in the admin panel; mobile presentation lands with ENG-513.

Product decision (2026-07-14): light headline status — the account leads with one word (Trial → Verified → Business) with capability badges as supporting detail.

The state machine

Account = { verified, bankPayout, business, usdAccount }

verified (phone + ID)                    → L1
+ bankPayout, individual                 → L2  (business-less Pro — ENG-515)
+ business (name + address) + bankPayout → L3
usdAccount (Bridge KYC)                  → orthogonal flag, any level ≥ L1

• GraphQL capabilities/statusHeadline resolve from one memoized derivation per account per request (WeakMap keyed on the account object) — one ERPNext lookup no matter how many fields ask; the Bridge-KYC "approved" literal is a typed domain constant (BRIDGE_KYC_APPROVED).
• src/domain/accounts/capabilities.ts — pure derivation: deriveLevelFromCapabilities, deriveStatusHeadline, deriveCapabilitiesForAccount (read model over stored level + ERPNext bank accounts + bridgeKycStatus, with grandfathering for existing L2/L3 accounts).
• GraphQL: capabilities: AccountCapabilities! and statusHeadline: AccountStatusHeadline! on ConsumerAccount (public) and AuditedAccount (admin). level stays exposed but documented as internal.
• Capability transitions: new accountCapabilityUpgradeRequest mutation — the client asks for one capability (BANK_PAYOUT or BUSINESS); the target level is derived server-side and the request flows down the existing ERPNext Account Upgrade Request pipeline unchanged. businessAccountUpgradeRequest (whole-tier) remains for existing clients.
• Full spec: docs/account-capabilities.md.

Testing

• TEST="capabilities|request-capability-upgrade|get-account-capabilities" yarn test:unit — 27 tests: derivation matrix, headline mapping, grandfathering, round-trip; requestCapabilityUpgrade routing (unverified / already-has / missing-bank / L2 add-bank / L3 reuse-on-file); getAccountCapabilities ERPNext-failure fallback, no-erpParty skip, and memoization semantics.
• Full unit suite: 135 suites / 1064 passed.
• yarn tsc-check clean; SDL regenerated via yarn write-sdl (public + admin + supergraph).

Local testing

query { me { defaultAccount { ... on ConsumerAccount { statusHeadline capabilities { verified bankPayout business usdAccount } } } } }

mutation { accountCapabilityUpgradeRequest(input: {
  capability: BANK_PAYOUT
  fullName: "Test User"
  address: { title: "Home", line1: "1 Main St", city: "Kingston", state: "St Andrew", country: "Jamaica" }
  bankAccount: { bankName: "NCB", bankBranch: "Half Way Tree", accountType: "Savings", currency: "JMD", accountNumber: "123456789" }
}) { id status errors { message } } }

🤖 Generated with Claude Code

[linear]

ENG-516

[islandbitcoin]

Review — capability state machine (ENG-516)

Domain derivation module + the 15-test matrix are solid. Four items to action before merge:

1. 🔴 CI is red — new mutation not registered in scope-map.ts.
api-key-scope-enforcement.spec.ts › "maps every authed root field" fails: accountCapabilityUpgradeRequest is unmapped (deny-by-default net). Add accountCapabilityUpgradeRequest: "BLOCKED" to src/domain/api-keys/scope-map.ts (matches its sibling businessAccountUpgradeRequest). The full yarn test:unit is red — the scoped TEST=capabilities run hid it; run the full suite before green-claiming.

2. 🟠 An unverified (L0) account can mint an L2 upgrade request.
request-capability-upgrade.ts computes level = deriveLevelFromCapabilities(...) — correctly L0 when !verified — but only special-cases === L3; L0/L1/L2 all fall through to an L2 request. The only downstream guard, AccountUpgradeRequest.validate() (AccountUpgradeRequest.ts:16), is requestedLevel <= currentLevel → reject, so 2 > 0 passes. Net: a phone-only, un-ID'd account can request bank-payout → L2, skipping the verified prerequisite the state machine is built on. Add if (!targetCapabilities.verified) return new ValidationError(...) before creating the request. (Pre-existing at the validate layer, but this handler is the one that derives L0 and then ignores it.)

3. 🟡 input.bankAccount as BankAccount (request-capability-upgrade.ts:78) casts away undefined.
On the business-with-on-file-bank path input.bankAccount is undefined; the cast satisfies createUpgradeRequest's L3 type (bankAccount required) but sends empty bank fields to ERPNext. No crash (validate() uses this.bankAccount?.…), but a grandfathered account whose ERPNext bank is missing/null → an incomplete L3 request. Make the L3 bankAccount optional in the type (honest) or confirm a real bank exists before deriving business.

4. 🟡 requestCapabilityUpgrade has no tests.
The 15 tests cover the pure functions; the mutation orchestration — where #2 and #3 live — is untested. Add: unverified → rejected, business with on-file bank (no bankAccount submitted), and already-has-capability.

Minor: the read-model derived level can exceed the still-exposed stored level (an L1 account with a bank on file reads bankPayout: true → implies L2). Known per your "consistent accounts" round-trip test; worth a doc note since both fields ship over GraphQL.

Blocking: #1 and #2.