feature/INT-1701 - Representative documents alignment

[david-ruiz-cko]

This pull request introduces several new document classes and updates the structure and documentation of the Accounts API onboarding models to more accurately represent the requirements for different onboarding variants. The changes clarify where different types of documents should be attached (either at the top-level or on representatives), add detailed PHPDoc comments, and introduce new enums for document types. The most important changes are grouped below:

New document models and enums

• Added new classes for specific document types: AdditionalDocument, CertifiedAuthorisedSignatory, FinancialVerification, ProofOfPrincipalAddress, ProofOfLegality, ProofOfRegistration, and ProofOfResidentialAddress, each with required fields and detailed documentation. [1] [2] [3] [4] [5] [6] [7]
• Introduced corresponding enums for document types: CertifiedAuthorisedSignatoryType, FinancialVerificationType, ProofOfPrincipalAddressType, ProofOfLegalityType, ProofOfRegistrationType, and ProofOfResidentialAddressType. [1] [2] [3] [4] [5] [6]

Refined document attachment structure

• Added RepresentativeDocuments class to strictly define the set of documents allowed on a representative, and updated the Representative class to use it instead of the general OnboardSubEntityDocuments. [1] [2]
• Improved comments and structure in OnboardSubEntityDocuments to clarify which documents belong at the top level and which on representatives, and updated types for new document classes. [1] [2]

Documentation and field clarifications

• Enhanced PHPDoc comments throughout, specifying requirements, field formats, and onboarding variant applicability for document fields and classes. [1] [2] [3]
• Added new Invitee class and related field in ContactDetails to represent the user responsible for onboarding. [1] [2]

These changes improve the clarity, maintainability, and correctness of the onboarding document model in the Accounts API.

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• exceeds_bounded_scope:453>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 24

---

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
exceeds_bounded_scope — 453>250	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🟢 Advisory review: Looks good to me

This PR still needs a human approval — wall-e cannot auto-approve it. For what it's worth, I read the diff and found nothing I'd block on.

This PR adds new document model classes and enums for the Accounts API onboarding, introduces RepresentativeDocuments to replace the incorrect OnboardSubEntityDocuments on Representative::$documents, and adds comprehensive tests verifying both serialization and wire-level behavior. The implementation matches the stated intent, the type changes are consistent throughout, and the deprecation of Identification::$document is handled correctly.

What I checked

• All new document classes (AdditionalDocument, CertifiedAuthorisedSignatory, FinancialVerification, ProofOfPrincipalAddress, ProofOfLegality, ProofOfRegistration, ProofOfResidentialAddress) are internally consistent: their PHPDoc type enums match their corresponding *Type class values.
• RepresentativeDocuments correctly restricts fields to only the four the API accepts, and the serialization test in RepresentativeDocumentsSerializationTest verifies this via reflection, which is a sound regression guard.
• The @Skip removal on shouldUploadAndRetrieveFile in AccountsIntegrationTest is a real behavioral change — that test will now run against the live sandbox; if the file upload endpoint is still flaky or unavailable, this could cause CI failures.
• The Representative::$documents type change from OnboardSubEntityDocuments to RepresentativeDocuments is a breaking change for any caller passing a full OnboardSubEntityDocuments instance to that field, but the backward-compatibility test (testBackwardCompatibleArrayAssignmentStillSerializesCorrectly, visible in RepresentativeDocumentsSerializationTest) confirms array-based callers are unaffected.
• The Identification::$document deprecation is documented and non-breaking — the field is retained with a @deprecated tag pointing to the correct replacement, which is appropriate.
• The eeaSoleTraderRepresentativeDocumentsReachTheWire test in AccountsSchemaVersionHeaderTest validates the actual serialized bytes, making it a strong guard against silent regression.
• File ID regex in PHPDoc (^file_[a-z2-7]{26}$, length 31) is consistent across all new document classes.

⚠️ The diff was too large to read in full, so this review covers only part of the change.

---

_{This is not an approval. wall-e cannot auto-approve this PR — it is an opinion to help whoever does. Advisory review · us.anthropic.claude-sonnet-4-6 · wall-e 2026.06.19-02}

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• exceeds_bounded_scope:625>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 35

---

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
exceeds_bounded_scope — 625>250	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[sonarqubecloud]

Quality Gate passed

Issues
10 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud