# Simulation Execution Status

## Phase 0 — Inventory & control design

**Status: COMPLETE**

The full-system plan and validation matrix are saved in `FULL_SYSTEM_SIMULATION_VALIDATION_PLAN.md`.

## Phase 1 — Deterministic simulation foundation

**Status: COMPLETE / MERGED**

Merged in PR #129 after all Foundation CI jobs passed.

Controls established:

- 3 simulation branches;
- 13 representative staff accounts with canonical role and branch assignment;
- 15 financial accounts;
- exact opening account control: TZS 229,000,000.00;
- 12 customers split across NIN and non-NIN identity modes;
- 4 loan products covering flat, reducing-balance and fixed-amount interest plus monthly, weekly, biweekly and lump-sum schedules;
- opt-in, production-safe simulation runner.

A validation failure in the first CI run confirmed branch-scoped models correctly fail closed outside branch/system context. The validation queries were corrected without weakening branch isolation.

## Phase 2 — Loan lifecycle & customer risk

**Status: COMPLETE / MERGED**

Merged in PR #130 after the full PHPUnit suite, production config/cache, MySQL migrations/preflight and release verification all passed.

Deterministic scenarios:

- draft application;
- application under review;
- rejected application;
- secured approved/ready-for-disbursement loan with guarantor, collateral and contract states;
- active loan with partial payment;
- completed loan;
- overdue loan with fixed late-payment penalty;
- active loan with pending, rejected and approved remote-payment submissions.

Validated independent monetary controls:

- customer disbursements: TZS 3,900,000.00;
- posted loan collections: TZS 1,169,000.00;
- cash processing fee: TZS 15,000.00;
- financial-account total after Phase 2: TZS 226,284,000.00.

The phase uses the real application services for application creation, approval, contract status, disbursement, payment allocation, remote-payment verification, accounting entries, penalty assessment and arrears refresh.

## Phase 3 — Advanced loan adjustments

**Status: COMPLETE / MERGED**

Merged in PR #131 after the full PHPUnit suite, production config/cache, MySQL migrations/preflight and release verification all passed.

Validated scenarios:

- top-up with authorized eligibility override, independent approval and cashier execution;
- adjusted early settlement;
- approved restructuring;
- rejected restructuring;
- approved write-off with supporting evidence and partial recovery;
- rejected write-off.

Validated cumulative controls:

- Phase 2 starting financial-account total: TZS 226,284,000.00;
- top-up internal settlement: TZS 1,155,000.00;
- replacement principal: TZS 1,400,000.00;
- top-up net cash: TZS 245,000.00;
- adjusted early-settlement cash receipt: TZS 783,000.00;
- write-off recovery cash: TZS 200,000.00;
- financial-account total after Phase 3: TZS 222,922,000.00.

Restructuring decisions and write-off approval were verified not to move cash; their schedule/accounting-journal effects are validated separately.

## Phase 4 — Accounting & operational finance

**Status: COMPLETE / MERGED**

Merged in PR #132 after the full PHPUnit suite, production config/cache, MySQL migrations/preflight and release verification all passed.

Validated scenarios:

- deterministic opening-balance ledger transactions and balanced opening journals for all 15 simulation accounts;
- TZS 5,000,000.00 capital injection;
- TZS 2,000,000.00 bank-to-cash internal transfer;
- approved TZS 300,000.00 operating expense;
- rejected TZS 250,000.00 expense with no cash effect;
- recurring TZS 120,000.00 expense generated as pending;
- August payroll prepared by HR, approved by branch manager and paid by accountant for TZS 1,200,000.00;
- TZS 2,500,000.00 fixed-asset purchase;
- TZS 100,000.00 depreciation posting;
- TZS 150,000.00 maintenance posting;
- exact cash reconciliation for Dar cash, petty-cash and safe accounts;
- manager-confirmed Dar daily closing.

Independent controls:

- opening ledger transactions: 15;
- opening ledger value: TZS 229,000,000.00;
- Phase 3 starting account total: TZS 222,922,000.00;
- internal transfer net cash effect: TZS 0.00;
- financial-account total after Phase 4: TZS 223,772,000.00;
- Dar physical/ledger cash at closing: TZS 32,315,000.00;
- all Dar cash reconciliations close with zero variance.

The opening-ledger bridge was added because daily closing reconstructs historical cash from financial-account transactions rather than trusting current balances. This keeps the simulation aligned with the same ledger shape produced by normal account creation without resetting validated balances.

## Phase 5 — Operational surfaces

**Status: COMPLETE / MERGED**

Merged in PR #133 after Foundation CI run #462 passed the full PHPUnit suite, production configuration/cache, MySQL migration/performance preflight and complete release verification including backup/restore.

Validated deterministic scenarios:

- production `TaskAutomationService` creates an overdue-collection task from the known 43-day overdue Dar loan;
- a completed Arusha document-review task provides a second branch, assignee and terminal task state;
- scheduled Dar and completed Arusha customer appointments exercise calendar state and branch separation;
- `LoanReminderService` dispatches through the `in_system` provider only, producing a persisted notification log and Laravel database notification without external SMS, email or WhatsApp transport;
- `ManagementAlertService` creates the 43-day overdue-threshold alert from the same known loan;
- successful and failed login attempts exercise the security-attempt ledger with deterministic IP/user-agent values;
- task and appointment creation/status changes produce auditable actor-attributed records;
- management calendar assertions prove Dar and Arusha operational events do not cross branch scope;
- ordinary simulation roles are used for branch/permission assertions; no super-administrator bypass is used.

Phase control:

- Phase 5 is explicitly non-financial;
- financial-account total before and after Phase 5 remains exactly TZS 223,772,000.00;
- task, appointment, reminder, notification, alert, audit and security records are idempotent across reruns.

## Phase 6 — Reports & dashboard reconciliation

**Status: COMPLETE / MERGED**

Merged in PR #134 after Foundation CI run #471 passed the full PHPUnit suite, production configuration/cache, MySQL migration/performance preflight and release verification.

Independent report controls cover:

- closing financial-account total and account-type balances;
- all-time cash-flow inflows/outflows and capital;
- collections, cash disbursements, approved expenses and payroll;
- Profit & Loss income/expense categories and net result;
- active portfolio principal, interest, fees, penalties, total outstanding, arrears and PAR;
- Dar, Mwanza and Arusha branch portfolio/flow controls;
- fixed-asset cost, accumulated depreciation, book value, period depreciation and maintenance.

Reconciliation implementation:

- `FinancialReportService` Profit & Loss includes depreciation expense and fixed-asset maintenance, matching the advanced Income Statement category coverage;
- `ManagementDashboardService` income/expense series uses the same expense category set as Profit & Loss;
- the read-only `report-reconciliation` simulation phase reruns the deterministic Phases 1–5 dataset without adding Phase 6 business transactions;
- regression tests compare FinancialReportService, AdvancedFinancialReportService, LoanBranchReportService and ManagementDashboardService against independent controls;
- financial, loan and fixed-asset CSV exports plus cross-branch report denial are validated.

## Phase 7 — Full end-to-end regression & CI gate

**Status: COMPLETE / VALIDATED — PR #135 READY TO MERGE**

Foundation CI run #474 validated the full simulation head `c56d7bf5be118bdd19c40d219cacf377ce9f8d2c` with all six gates green:

- full PHPUnit suite — PASS;
- SQLite full simulation — PASS;
- MySQL 8.0 full simulation — PASS;
- MySQL migration/performance preflight — PASS;
- production configuration/cache gate — PASS;
- release verification, operational health and backup/restore drill — PASS.

Both dedicated simulation jobs execute the same real sequence:

1. fresh migrations plus the normal application seed;
2. full deterministic `SimulationSeeder`;
3. a second full simulation seed to prove idempotency;
4. `simulation:validate --json` against independent controls.

Final controls include foundation counts, closing cash/account balances, Profit & Loss, cash flow, portfolio/PAR, trial balance, statement of financial position, loan reports, fixed assets, overdue operations, tasks, appointments, reminders, management alerts, security login attempts and branch isolation.

### Cross-database defect discovered and fixed

The first Phase 7 MySQL run exposed a false stale-restructuring rejection. `previous_schedule` is stored as JSON; MySQL native JSON can reorder object keys while SQLite text JSON preserves insertion order. The approval guard used PHP strict array identity, making identical schedules compare as different on MySQL.

`LoanRestructuringService` now canonicalizes both schedule snapshots before strict comparison, normalizing key order and typed business values while preserving installment order. The corrected MySQL job then passed the full double-seed simulation and validator.

The detailed final matrix is recorded in `FINAL_SIMULATION_VALIDATION_MATRIX.md`.

## Simulation program result

**ALL PHASES 0–7 COMPLETE.**

No simulation-specific blocker remains. The full-system simulation is deterministic, idempotent, independently reconciled, branch-isolation aware and reproducible on both SQLite and MySQL. PR #135 only needs its final post-documentation CI pass before merge.
