# TestLotReplay: 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

- input.stdf + optional settings.json
- attempts.csv + optional settings.json
- input.json alone, including explicitly ordered sources for multi-file history

| File | Format | Sample columns |
|---|---|---|
| `input.stdf` | STDF |  |
| `settings.json` | JSON |  |
| `attempts.csv` | CSV | `lot`, `wafer`, `x`, `y`, `device_id`, `attempt_order`, `head`, `site`, `pass_status`, `hard_bin`, `soft_bin` |

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
{}
```

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` |  |
| `attempts.csv` | `device_id`, `elapsed_ms`, `file`, `file_order`, `hard_bin`, `head`, `identity`, `lot`, `num_tests`, `offset`, `part_flags`, `pass_status`, `pir_offset`, `site`, `soft_bin`, `wafer`, `x`, `y` |
| `bins.csv` | `devices`, `hard_bin`, `lot`, `soft_bin`, `status` |
| `completeness.json` | `findings`, `status`, `summary` |
| `devices.csv` | `attempts`, `device_id`, `final_file`, `final_offset`, `final_status`, `first_file`, `first_offset`, `first_status`, `identity`, `lot`, `wafer`, `x`, `y` |
| `index.html` |  |
| `input.json` | `schema`, `settings`, `stdf_base64` |
| `manifest.json` | `schema`, `sha256`, `version` |
| `measurements.csv` |  |
| `policy.json` | `chronology`, `final`, `first`, `identity`, `rotation_degrees`, `scope`, `unknown` |
| `report.json` | `findings`, `provenance`, `status`, `summary`, `tables` |
| `retest-transitions.csv` | `devices`, `final_status`, `first_status` |
| `source-00.stdf` |  |
| `source-record-offsets.csv` | `file`, `file_order`, `length`, `offset`, `subtype`, `type` |
| `styles.css` |  |
| `test-summaries.csv` |  |
| `wafer-2d1d8bbd506c0dfae98f38fd-final.svg` |  |
| `wafer-2d1d8bbd506c0dfae98f38fd-first.svg` |  |
| `wafer-map.svg` |  |

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 contractor STDF files → TestLotReplay** (STDF V4 + JSON): Retain original bytes, select identity policy, and declare source precedence in an input.json sources list. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.
- **devices.csv + retest-transitions.csv + completeness.json → Buyer-owned descriptive yield review** (CSV + JSON): Use resolved-device denominators, keep first and final outcomes distinct, and read completeness before aggregating. No tester or MES API connection. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.

## Scope boundaries

- Bounded STDF V4 subset, IEEE little/big endian. Up to 32 sources and 8 MB combined binary input per engine job.
- Explicit part-ID or wafer-coordinate identity and file chronology; unsupported records or incomplete episodes withhold dependent totals.
- No universal tester compatibility, STDF editing, equipment map, Cpk, process recommendation or manufacturing acceptance.
- The result attempts.csv contains provenance columns and is not automatically accepted as normalized input. Select the documented input columns explicitly.

## Replay evidence

Engine SHA256: `8a90154ee3485428e140c1f06434124f5a37f820566233f218a3d6cffef89685`.

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.