# MFI-MIG-CLIENT-UNIT-OWNERSHIP — Certified Standard

**Status:** Active (supersedes per-Fortress-branch client `loan_branch_id` placement)  
**Aligns with:** ORG-05 organization tree (4 operational units)

---

## Rule

Migrated **clients** and **loans** attach to the **primary unit `loan_branch`** for their organization unit — the row whose `code` matches the org unit code (e.g. `NYAHURURU-UNIT`).

They do **not** attach to secondary operational projections (`NYAHURURU-UNIT-5`, `OLKALOU-GILGIL-UNIT-3`).

---

## Resolution chain

```text
Fortress org1_clients.branch / org1_loans.branch (integer id)
  → migration_branch_maps.source_branch_id
  → organization_unit_id                    (org truth — roll-up)
  → primary loan_branch where code = unit code (client/loan ownership)
```

**Preserved for audit (not on client row ownership):**

- `migration_client_maps.meta_json.fortress_branch_id`
- `migration_client_maps.meta_json.fortress_source_branch_map_code`
- `migration_client_maps.meta_json.fortress_operational_loan_branch_id`
- `loan_clients.biodata_meta.fortress_branch_id`

Secondary `loan_branches` rows remain for payment reconciliation keys only.

---

## Examples

| Fortress branch id | Legacy name | Org unit | Client/loan `loan_branch` code |
|---:|---|---|---|
| 2 | nyahururu | Nyahururu Unit | `NYAHURURU-UNIT` |
| 5 | rumuruti | Nyahururu Unit | `NYAHURURU-UNIT` (not `-5`) |
| 1 | gilgil | Olkalou/Gilgil Unit | `OLKALOU-GILGIL-UNIT` |
| 3 | olkalou | Olkalou/Gilgil Unit | `OLKALOU-GILGIL-UNIT` (not `-3`) |
| 4 | nakuru | Nakuru Town Unit | `NAKURU-TOWN-UNIT` |
| 11 | kiawara | Kiawara Unit | `KIAWARA-UNIT` |
| 6 | nakuru hq | Nakuru HQ | `NAKURU-HQ` |

---

## Loans

Loan `loan_branch_id` follows the **same primary unit branch** as the client (not the raw Fortress branch map row).

Fortress source branch is stored on loan `form_meta.migration`.

---

## Reconciliation

For already-migrated portfolios on secondary rows:

```bash
php artisan mig:client-ownership-reconcile --dry-run
php artisan mig:client-ownership-reconcile --apply
```

Updates `loan_clients`, `loan_book_loans`, and `migration_client_maps`.

---

## UI

Client register branch filters use **one option per unit name** (primary branch row only).