Skip to main content

ADR-0061: Role-based LegalArrangement model + separate UBO determination path

Status: Accepted Date: 2026-06-16 Supersedes: none Superseded by: none Deciders: Adrian (Soft4U), Claude Opus 4.8

Decision context:

  • Latency: none — pure in-memory model + determination.
  • Dependency surface: no new packages. Adds legal_arrangement.py models + arrangement_ubo.py.
  • Debuggability: each arrangement UBO carries reason_code=arrangement_<role> + an AMLR Art. 58 audit note; the determination is a pure function.
  • Reversibility: branch revert; additive (new module, no existing model changed).
  • Blast radius: additive; the ownership-graph engine (ADR-0053/0054/0055) is untouched.
  • Alternative considered: reuse the ownership-% graph with role tags (rejected — a trustee with 0% is a UBO; a synthetic percentage would corrupt the ownership arithmetic).

Context​

No domain model for legal arrangements existed — trusts/foundations could only be mis-shaped into the percentage-based ownership graph. AMLR Art. 58 requires role-based beneficial-owner determination for arrangements: a settlor/trustee/protector/beneficiary (trust) or founder/governing-body (foundation) is a beneficial owner by role, regardless of any ownership percentage.

Decision​

A new role-based model + a separate role-based UBO determination, distinct from the ownership-% engine:

  1. Models (trustrelay-models/legal_arrangement.py): ArrangementType (express_trust/foundation/ similar), ArrangementRole (settlor/trustee/protector/beneficiary/founder/governing_body/ other_controlling_person), ArrangementParty, LegalArrangement — carrying no ownership_percentage by design.
  2. Determination (arrangement_ubo.compute_arrangement_ubos): every listed party is a BeneficialOwnerResult (qualified=True, qualified_via=["arrangement_role"], reason_code=arrangement_<role>, aggregated_pct=0.0) — first-class alongside ownership/control/SMO UBOs.

Consequences​

Positive​

  • Trusts/foundations are modelled correctly (role-based); all parties surface as UBOs without any percentage; reuses BeneficialOwnerResult so consumers treat all UBO bases uniformly.

Negative​

  • A second UBO determination path alongside the ownership-graph engine — intentional; the two are structurally different (% vs role).

Neutral​

  • Onboarding-flow routing (detect arrangement cases and use this path) + graph/goAML persistence of arrangements are pipeline follow-ups; this delivers the model + determination they consume.

Alternatives Considered​

Alternative 1: Reuse the ownership-% graph with role tags​

Rejected — the central point of the issue: a trustee/settlor with 0% ownership is a beneficial owner. Forcing a synthetic percentage into the ownership engine would corrupt its multi-path summation arithmetic and misrepresent the legal reality.