# Wallet Dashboard Operations

## Purpose and access

The tenant Wallet Dashboard is a read-only view of the approved Wallet Foundation. Existing Tenant Administrator and Finance memberships may view it. Other tenant roles receive a denial, and all wallet and transaction lookups remain tenant-scoped. Financial mutations remain available only to authorized platform operations through the established Artisan tooling.

The page displays the authoritative stored available balance, TZS currency, active or frozen state, bounded credits and debits, transaction count, cursor-paginated ledger history, safe transaction details, and the latest persisted reconciliation state. It does not offer credit, debit, adjustment, reversal, freeze, unfreeze, funding, pricing, payment, invoice, or SMS charging controls.

## Balance and immutable ledger

All amounts are integer minor units and TZS is rendered as whole shillings, for example `TZS 125,000`. The operational balance comes directly from the wallet projection; Blade does not recalculate it. Ledger transactions remain append-only. A reversal is displayed as a new compensating transaction linked to its immutable original.

The dashboard presents only Credit, Debit, Adjustment Credit, Adjustment Debit, and Reversal. Internal numeric identifiers, idempotency fingerprints, diagnostic details, credentials, and metadata are not selected for presentation.

## Reconciliation snapshots

`WalletReconciliationService` remains the authoritative full-ledger verifier and is deliberately unbounded. It is never called by a dashboard request. The operational `gateway:wallet:reconcile` command invokes it explicitly and, only after verification completes, updates one current `wallet_reconciliation_snapshots` row for the wallet.

Snapshots contain only status, UTC verification time, transaction count, projected and derived balance summaries, and a safe generic diagnostic code. A completed healthy run records `reconciled`; a completed mismatch records `attention_required` and retains the command's non-zero exit. A runtime failure before completion leaves the prior snapshot unchanged. Snapshot writes never repair or mutate the wallet or ledger.

The dashboard renders these states as Reconciled, Attention Required, or Not Yet Verified. The UTC verification timestamp makes clear that the status describes the last completed verification rather than guaranteeing that no later transactions exist.

## History and filtering

History defaults to the last 30 UTC days and supports a maximum 90-day range. The From boundary is inclusive and the To boundary is exclusive. Filters are limited to approved transaction type and exact indexed transaction/reference identifiers. Page sizes are 25, 50, or 100. Cursor ordering is `occurred_at DESC, id DESC`, and query parameters persist between pages.

## Manual verification

1. Initialize a tenant wallet through approved operational tooling if necessary.
2. Create controlled credit and debit transactions with the approved Artisan commands.
3. Run the reconciliation command and note its result and UTC time.
4. Sign in as a Tenant Administrator or Finance member and open Finance, then Wallet.
5. Confirm the balance, selected-range totals, status, transaction count, and reconciliation timestamp.
6. Filter by UTC date and type, then search an exact transaction or reference ID.
7. Open transaction details and verify reversal links where applicable.
8. Freeze a test wallet operationally and confirm the read-only Frozen explanation.
9. Confirm that no financial mutation buttons or forms exist.
10. Confirm another tenant and a non-finance role cannot access wallet or transaction URLs.
11. Repeat through the deployed base path and LAN/public host to confirm generated links preserve the current base URL.

No deployment is performed as part of this milestone.