# Run & Deploy — Cash Recovery Engine

## Requirements

- Node.js 18+ (tested on Node 24). No npm install — zero runtime dependencies.
- No network access required.

## Run locally

```bash
cd delivery-package/cash-recovery-engine
node run.mjs        # writes reports/ + public/ledger.js
node verify.mjs     # writes verification-report.json/.md + evidence copy
```

Open `public/tool.html` directly in a browser (it loads `public/ledger.js`).

## Deploy the web tool

The tool is a single static HTML file plus a generated `ledger.js` data file.
Serve the `public/` folder from any static host (or use the Forge publish
pipeline, which copies it to `published/cash-recovery-engine/tool.html`). No
server-side runtime is needed — the engine's scores are precomputed by
`node run.mjs` and the optimizer re-runs client-side.

## Bring your own AR data (closing the real-data seam)

The verification suite auto-detects a real dataset. Provide two CSV files:

### `data/official/history.csv` — resolved invoices (to learn from)

One row per *closed* invoice, with the eventual outcome and whether a collector
worked it:

```
invoice_id,customer_id,account_segment,amount_usd,days_past_due,aging_bucket,prior_late_ratio,avg_days_to_pay,disputed,size_vs_median,reminders_sent,credit_health,relationship_months,effort_hours,days_to_pay,worked,paid_within_horizon
```

- `worked` ∈ {0,1} — was this invoice actively worked by a collector?
- `paid_within_horizon` ∈ {0,1} — did it pay within the collection horizon?
- `disputed` ∈ {0,1}; `credit_health` ∈ [0,1]; ratios as decimals.

### `data/official/open.csv` — live open invoices (to act on)

Same columns; `worked`/`paid_within_horizon` may be blank for currently-open
items (they are only used for the control-AUC check on rows where `worked=0`).

Then:

```bash
node verify.mjs     # runs the identical checks on your data + an official block
```

### Field mapping from common AR systems

| Engine field | Typical AR/ERP source |
| --- | --- |
| `amount_usd` | invoice open balance |
| `days_past_due` | today − due date |
| `prior_late_ratio` | share of the customer's past invoices paid late |
| `avg_days_to_pay` | customer historical DPD-to-pay average |
| `credit_health` | normalized credit score / risk rating (0–1) |
| `worked` | dunning/collections activity log flag |
| `paid_within_horizon` | settled within N days of the snapshot |

## Important deployment note

This engine recommends *where to spend collector time*; it does not move money,
post to the ledger, or contact customers. Treat its output as a decision-support
worklist. Validate uplift on your own data with a holdout or A/B test before
attributing recovered cash to it — see `proof/LIMITATIONS.md`.
