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 variants, introduces RepresentativeDocuments to correctly scope per-representative documents, fixes the ETag/If-Match header passthrough in updateBankPaymentInstrumentDetails, and improves PHPDoc throughout. The diff matches its stated intent and the functional change (passing headers as the 4th argument to apiClient->patch) is backed by a new focused unit test.

What I checked

• The functional change in AccountsClient.php correctly passes instrumentRequest->headers as the 4th argument to apiClient->patch, matching the comment that the API requires If-Match as an HTTP header; the new shouldSendUpdateBankPaymentInstrumentEtagAsIfMatchHeader test verifies this call signature.
• The wire-level test eeaSoleTraderRepresentativeDocumentsReachTheWire in AccountsSchemaVersionHeaderTest.php verifies that representative documents serialize into the correct JSON path and that top-level documents contain only bank_verification, catching accidental misplacement of keys.
• Identification::$document is correctly marked @deprecated with guidance to use RepresentativeDocuments::$identity_verification instead, and the field is retained for backwards compatibility rather than removed.
• The note in Identification.php that $document 'is not part of any Accounts API schema' and 'the API does not read it' is an honest documentation of a pre-existing footgun rather than something introduced here.
• All new enum classes (CertifiedAuthorisedSignatoryType, FinancialVerificationType, etc.) are plain PHP classes with static string properties, consistent with the existing pattern in the codebase.
• The diff is truncated so the complete integration test for shouldUpdatePaymentInstrumentWithEtag and portions of AccountsSchemaVersionHeaderTest are not visible; no conclusion can be drawn about those sections beyond what is shown.

⚠️ 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}

[agent-wall-e]

🟡 Risk Classification: MINOR

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

Classification reasons

• exceeds_bounded_scope:678>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 47

---

_{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 — 678>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
11 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