feature/INT-1701 - Representative documents alignment

[david-ruiz-cko]

This pull request significantly expands and updates the integration and serialization tests for account onboarding entities, with a focus on schema 3.0 and representative document handling. It introduces new test cases for uploading and linking representative documents, adds utility methods for building valid company requests, and improves coverage for EEA Sole Trader scenarios. The changes ensure the SDK's test suite accurately reflects the latest API requirements and behaviors.

Integration test enhancements:

• Added new tests to verify onboarding of entities with representative documents, including identity verification and certified authorised signatory, and ensured that documents are echoed back by the API (test_should_onboard_entity_with_representative_documents).
• Added tests for uploading EEA Sole Trader proof files and retrieving them, covering the required purposes (test_should_upload_representative_proof_files).
• Updated the file upload and retrieval test to use a schema 3.0 entity and the correct file purpose (test_should_upload_entity_file_and_retrieve).

Test utility improvements:

• Introduced a build_company_v3_request helper to generate valid schema 3.0 company onboarding requests, reducing duplication and improving test maintainability.
• Enhanced the upload_file utility to support customizable file purposes for more flexible test scenarios.

Serialization test coverage:

• Added serialization tests for EEA Sole Trader representative documents, ensuring correct JSON structure and key presence, and validating that only accepted keys are declared in RepresentativeDocuments.
• Added regression and edge case tests to verify omission of unset attributes and correct handling of None values in representative documents.
• Added a test for serializing a controlling company as a representative, ensuring company structure is handled correctly.

Imports and dependency updates:

• Updated imports in test files to include new document-related classes and enums required for the new tests. [1] [2]

[agent-wall-e]

🟡 Risk Classification: MINOR

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

Classification reasons

• exceeds_bounded_scope:402>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 3

---

_{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 — 402>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 serialization tests for representative documents, new integration tests for schema 3.0 representative document uploading, and inline documentation for accounts SDK classes. The changes appear correct and consistent with stated intent.

What I checked

• The unit test test_representative_documents_declares_only_the_keys_the_api_accepts asserting exact __annotations__ order is a reasonable regression guard, and the four keys listed match the RepresentativeDocuments class annotations visible in the diff.
• The change from FilePurpose.IDENTIFICATION to FilePurpose.IDENTITY_VERIFICATION in accounts_client_test.py is consistent with a corrected enum value and is reflected across the integration test helpers as well.
• The test_should_onboard_company_v3 test had its @pytest.mark.skip removed, meaning it will now run against the sandbox — this is intentional per the PR description but could cause flaky CI if the sandbox isn't in the expected state.
• The upload_file helper in the integration test now accepts a purpose parameter, which is a non-breaking change and correctly used by the new test cases.
• The diff is truncated so the full RepresentativeDocuments class body, build_company_v3_request helper, and upload_file utility changes are not fully visible, but what is shown is consistent and no logic errors are apparent in the visible portions.
• Inline documentation added to accounts.py, accounts_client.py, and files.py is accurate based on the visible diff and doesn't contradict the code.

⚠️ 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:405>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 3

---

_{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 — 405>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:504>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 6

---

_{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 — 504>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
0 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