# Outcome Contract — Cash Recovery Engine

## Request

Finance and revenue-operations teams sit on large balances of overdue
receivables and a fixed amount of collector time. The conventional worklist —
chase the oldest invoice, or the biggest balance — wastes that time on accounts
that would have paid anyway and on accounts that will not pay regardless of how
many calls they get.

Build a decision engine that, given an accounts-receivable ledger and a weekly
collector-hours budget, produces a **prioritized collections worklist** that
maximizes the cash actually recovered per collector-hour, and quantifies the
business impact (cash accelerated, days-sales-outstanding effect).

## Scope & honest constraint

No real company accounts-receivable ledger is present in this workspace, and
none can be retrieved from here. The contracted, verifiable outcome is therefore
a **complete, runnable receivables-prioritization engine** plus a documented
seam for real data — not a recovery number from a specific company's books.

What is delivered LIVE and verified:

- An **uplift (causal) model** that separates invoices that will *self-cure*
  from invoices a collector touch will actually convert (the "moveable middle").
- A **capacity-constrained optimizer** that fills a collector-hours budget with
  the highest expected-cash-per-hour invoices (0/1 knapsack, greedy-by-ratio).
- A **risk segmentation** (Persuadable / Self-Cure / At-Risk / Critical) with a
  recommended action per segment.
- **Downloadable deliverables**: a ranked worklist CSV, a structured JSON
  result, and a one-page executive summary.
- A **live web interface** that re-optimizes the worklist as the capacity dial
  moves and charts recovered cash vs. collector-hours against the conventional
  baselines.
- End-to-end **verification** on a synthetic AR benchmark with a known causal
  ground truth, plus an auto-detecting real-data evaluation path.

## Success criteria (MUST PASS)

1. `node run.mjs` trains the engine and writes a ranked
   `reports/collections-worklist.csv`, `reports/engine-output.json`, and
   `reports/executive-summary.md`.
2. `node verify.mjs` passes 100% of its checks, asserting:
   - the logistic learner recovers a known separable signal;
   - synthetic potential outcomes are monotone (working never reduces payment);
   - the optimizer never exceeds the hours budget;
   - self-cure propensity ranking (AUC) and calibration (ECE) clear thresholds;
   - the engine beats the strongest simple baseline on cash recovered by a
     clear margin, and recovers at least 2× the cash of FIFO at equal hours;
   - results are reproducible (seeded);
   - the worklist schema is complete and budget-feasible.
3. Deterministic, dependency-free Node (no network, no native deps).

## Out of scope

- Real cash collection, payment processing, or accounting-system integration.
- A claim of recovered cash for any specific company (a disclosed seam pending a
  real ledger and a holdout/A-B validation).

## Acceptance

Accepted when both MUST_PASS commands succeed on a clean checkout, the proof
package answers the ten IRS_AUDITOR questions, and the delivery package documents
exactly how to swap in a real AR export to produce a live worklist.
