Explanation

KycController.ts had grown to ~2,400 lines because it carried several unrelated concerns in one file: the phase machine and flow orchestration, the full state type plus its persistence metadata and defaults, pure consent-record helpers, and the UKYC attestation / capability-token wrapping glue. That made the actual orchestration logic hard to find and hard to test in isolation — the consent helpers, for instance, were module-private and could only be exercised through the controller.

This PR extracts the cohesive pieces into dedicated modules so the controller is left as the orchestrator it's meant to be. Each extracted module is domain-named rather than a generic utils.ts, so ownership stays obvious:

• src/KycControllerState.ts — the KycControllerState type, kycControllerMetadata, and the getDefaultKycControllerState / getDefaultKycVendorDisclaimersAccepted / getDefaultKycProviderDisclaimersAccepted factories.
• src/consents.ts — the pure consent-record and error-shape predicates: consentRecordKey, isSessionAlreadyCompletedError, isConsentConflictError, isValidConsentRecordList, consentRecordsFromAcceptedList, isAcceptedCategoryEmpty, acceptedCategoryStillMissing, and usesConsentsFlow.
• src/ukyc/sessionAuthorizations.ts — the attestation and capability-token wrapping glue: UKYC_CAPABILITY_TOKEN_TTL_MS, assertAttestedServerPublicKey, and wrapUkycSessionAuthorizations.

Two repeated blocks inside the controller were also folded into private helpers: #markAlreadyCompleted (the "session already completed" error branch, which appeared identically in two flows) and #refreshUserStatusSoft (the best-effort user-status refresh). Both keep the existing #generation guard so a reset() landing mid-flight still can't write onto an idle controller.

Net effect: KycController.ts goes from 2,424 to 1,954 lines.

This is a pure restructuring — no behavior change and no API change.

Documentation

ARCHITECTURE.md gains the new modules in its key-source-files appendix, along with vendorDisclaimerAcceptance.ts and src/ukyc/, which were already missing from that table. I also corrected some drift left over from #10082: the doc still described KycController as owning the frame protocol and an X25519 keypair named #keypair created at construction, when that material now lives in MoonPayFrameHandler as #frameKeypair and is minted when a MoonPay flow starts. The component diagram now routes the frame protocol and decryptCredentials() through the handler rather than the controller.

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them