# RoyaltyWaterfall: file and automation reference

This technical reference describes actual local interfaces. It is not a claim of a hosted API, vendor connector or additional paid calculation. The free tool and the fixed-version kit use the same engine.

## Inputs

- receipts.csv + rules.json + optional costs.csv and opening-state.json
- revenue.csv is an exclusive alias for receipts.csv
- input.json alone supports single or multi-project/period payloads

| File | Format | Sample columns |
|---|---|---|
| `receipts.csv` | CSV | `event_id`, `project_id`, `period`, `currency`, `amount_minor`, `source`, `reverses_event_id` |
| `rules.json` | JSON |  |

The actual files in `samples/file-input/` are synthetic fixtures. Optional file schemas and every semantic constraint are in the [engine README](README.md). Exact JSON structure is in the product schema and README. A filename is an exact basename, never a disk path passed to the engine API.

## CLI and Python

Run from an extracted trusted kit directory using Python 3.12 or newer. TileMosaic also requires the versions in `requirements.txt`.

```sh
python3 product.py samples/valid.json output-001
```

```python
import json
from pathlib import Path
import product
payload = json.loads(Path("samples/valid.json").read_text())
report = product.run(payload)
if report["status"] != "FAIL":
    Path("result-api.zip").write_bytes(product.bundle(payload))
print(report["status"])
```

For real files, use the common `run_files.py` example: it encodes PNG/STDF bytes with base64, passes text as UTF-8, and calls `files_to_payload` before the same `run`/`bundle` functions. These are local Python functions, not HTTP endpoints. Call `run_json(text)` for strict JSON parsing; duplicate keys and nonfinite numbers are refused.

## Batch folders and exact column profile

Each immediate subdirectory of `jobs/` is one independent engine payload. Copy all required files into that folder. Use `input.json` for a multi-period RoyaltyWaterfall history or an explicitly ordered multi-file TestLotReplay history; splitting those dependent histories into independent folders does not carry state.

```sh
mkdir -p jobs/example
cp samples/file-input/* jobs/example/
python3 batch.py jobs results-001
```

A profile maps destination header to source header. This complete example corresponds to the sample CSV files with every header renamed to `export_...`; normal sample headers need no profile.

```json
{
  "receipts.csv": {
    "event_id": "export_event_id",
    "project_id": "export_project_id",
    "period": "export_period",
    "currency": "export_currency",
    "amount_minor": "export_amount_minor",
    "source": "export_source",
    "reverses_event_id": "export_reverses_event_id"
  }
}
```

Save the profile as `columns.json` outside the job folder, then run `python3 batch.py jobs results-002 --profile columns.json`. For PNG/STDF/JSON-only inputs the profile is `{}` and can be omitted. Profiles rename columns only: no unit, currency, timestamp or value conversion. Destination order is significant for strict CSV readers. The outer runner deliberately projects only mapped columns; retain and review the original export. Missing/duplicate headers, ragged rows and nonunique mapped source columns fail. Engine-specific validation still runs after mapping.

## Result file schema observed by executable example

Columns and JSON keys observed in the synthetic PASS fixture; variable recipient, source, pyramid and map filenames depend on input. Read README.md for UNKNOWN omissions and semantic rules.

| ZIP member | CSV columns or observed JSON keys |
|---|---|
| `README.txt` |  |
| `carryforward.csv` | `pool`, `opening_minor`, `recouped_exact`, `closing_exact`, `closing_minor` |
| `index.html` |  |
| `input.json` | `costs`, `currency`, `opening_balances`, `period`, `project_id`, `receipts`, `schema`, `waterfall` |
| `inputs-manifest.json` | `input_sha256`, `schema`, `scope` |
| `manifest.json` | `files`, `schema`, `status`, `version` |
| `period-balances.csv` | `project_id`, `period`, `currency`, `status`, `receipts_minor`, `allocated_minor`, `unallocated_minor`, `closing_balances` |
| `period-balances.json` |  |
| `report.json` | `findings`, `provenance`, `status`, `summary`, `tables` |
| `rules.json` | `costs`, `currency`, `opening_balances`, `period`, `project_id`, `schema`, `waterfall` |
| `statements.csv` | `recipient_id`, `allocated_minor`, `currency` |
| `statements/1aca80e8b55c802f7b43740da2990e1b5735bbb323d93eb5ebda8395b04025e2.csv` | `recipient_id`, `allocated_minor`, `currency` |
| `statements/1aca80e8b55c802f7b43740da2990e1b5735bbb323d93eb5ebda8395b04025e2.html` |  |
| `statements/62f2f0f1eff10d3152c95f6f0596576e482bb8e44806433f4cf929792834b014.csv` | `recipient_id`, `allocated_minor`, `currency` |
| `statements/62f2f0f1eff10d3152c95f6f0596576e482bb8e44806433f4cf929792834b014.html` |  |
| `statements/70b1e8e06785cae451496104850781f33faf6cc8e0777ecd3a9ccaaefb154b2d.csv` | `recipient_id`, `allocated_minor`, `currency` |
| `statements/70b1e8e06785cae451496104850781f33faf6cc8e0777ecd3a9ccaaefb154b2d.html` |  |
| `styles.css` |  |
| `unallocated.csv` | `reason`, `amount_minor` |
| `waterfall-trace.csv` | `step`, `node_id`, `node_type`, `target`, `amount_exact`, `pot_before_exact`, `pot_after_exact` |

CSV text that could execute as a spreadsheet formula is neutralized; original JSON preserves exact text. Read report status and the relevant coverage/completeness fields before importing numeric rows. UNKNOWN is an unobserved result, not zero. PASS is computation under declared inputs and policies, not a professional conclusion.

## Supported handoffs

- **Buyer-owned receipts and approved rule program → RoyaltyWaterfall** (CSV + JSON): Export explicit project/period/currency/minor-unit rows; supply approved opening balances and ordered rules. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.
- **period-balances.json + statement CSVs → Buyer-owned next-period review** (JSON + CSV): Review carryforward against the exact accepted prior history. Copy only the relevant project/pool state or replay complete ordered periods; no automatic accounting posting. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.

## Scope boundaries

- Integer currency minor units and exact rational rates; currencies remain separate. Rules and chronology are supplied by the buyer.
- Statements are drafts. No contract interpretation, rights verification, tax, invoicing, sending or payments.
- A reversal requires complete affected history and restates earlier drafts; it does not recover money.
- Outer batch profiles rename columns only. Do not also apply a conflicting rules.json csv_mappings layer.

## Replay evidence

Engine SHA256: `f3de1e1e47e85c0081041a1985531b86a7ce17747d648db6259165013bd5b388`.

The documentation builder ran the actual synthetic file set and reopened its result archive. This verifies the local format example, not customer file compatibility, deployment, demand or financial return. Same-version bytes can be compared in one pinned environment; Python/zlib or TileMosaic dependency upgrades can change archive bytes.

See the [common automation reference](../integrations.md) for scheduling, CI and batch receipt semantics.