feat: add get_reconciliation view comparing token balance to outstanding liability

[Spagero763]

feat: add get_reconciliation view comparing token balance to outstanding liability

Closes #463

Summary

Adds a single read-only view, get_reconciliation, returning the contract's
solvency position: the live funding-token balance, the outstanding investor
liability, and the resulting surplus (sweepable dust) or deficit. This removes the
need for off-chain tooling to fetch the balance, funded amount, distributed
principal, and settlement state separately and re-derive the liability arithmetic
that sweep_terminal_dust already encodes.

Changes

• escrow/src/lib.rs
  • New #[contracttype] ReconciliationView { token_balance, outstanding_liability, surplus } with /// field docs.
  • New get_reconciliation(env) -> ReconciliationView:
    • outstanding_liability = max(funded_amount - distributed_principal, 0) — the same floor sweep_terminal_dust enforces, so the two never disagree (cross-referenced in the doc comment).
    • surplus = token_balance - outstanding_liability (negative = deficit).
    • Saturating arithmetic throughout; pure read, no auth, no storage writes.
• escrow/src/tests/external_calls.rs — tests asserting surplus equals the
  amount sweep_terminal_dust permits, before and after a partial refund, plus
  edge cases: zero balance, over-funded, fully-distributed, and "one unit over
  surplus panics".
• README.md / docs/escrow-read-api.md — documents the view on the read-API
  surface and the reconciliation guide.

Security notes

• outstanding_liability reuses sweep_terminal_dust's exact floor, so the view
  can never report a larger sweepable surplus than the sweep guard would allow.
• In settled (2) / withdrawn (3) states distributed_principal is 0, so the
  view reports outstanding_liability = funded_amount and is therefore
  conservative relative to sweep (which only applies the floor in cancelled
  state 4). It can never over-report sweepable funds.
• All arithmetic is saturating; the view cannot panic on extreme balances/amounts.

⚠️ Build status — pre-existing breakage on main (action needed)

cargo build / cargo test / cargo fmt --all -- --check cannot currently run
to completion on main, for reasons unrelated to this PR. A clean checkout of
main (HEAD 5de660f, "Merge branch 'pr-572'") with my changes reverted fails to
compile with the same 34 errors. The recent merge commits (pr-570/571/572)
left the escrow crate with, e.g.:

• duplicate definitions of rotate_beneficiary, BeneficiaryRotated,
  request_clear_legal_hold, get_legal_hold_clearable_at, get_attestation_digest_at;
• references to guard_status_in / guard_status_eq and an EscrowError::SweepNotTerminal
  variant that are not defined (the enum has DustSweepNotTerminal);
• duplicate enum discriminants and a non-exhaustive match on AmountExceedsMax.

I did not attempt to rewrite that merge: resolving dozens of errors spanning
settlement, claims, maturity, caps, and rotation in a financial contract would mean
guessing maintainer intent and risks introducing real bugs. It needs a maintainer
fix (or a clean re-merge of pr-572).

This PR is intentionally scoped to issue #463 and touches only three files. My
additions are isolated to the end of lib.rs (after get_distributed_principal)
and the end of external_calls.rs, are rustfmt-clean (verified: cargo fmt
reports no diffs in the added ranges), and are type-correct against existing APIs
(get_escrow, DataKey::DistributedPrincipal, funding_token_or_fail,
TokenClient, escrow.funded_amount).

Once main compiles, the included tests assert surplus == sweepable dust
across the zero-balance, over-funded, partial-refund, and fully-distributed states.
I'm happy to rebase and paste full cargo test output as soon as the tree builds.

[drips-wave]

@Spagero763 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[mikewheeleer]

really nice — merging this 🙌