# TestLotReplay 1.0.0

Offline descriptive replay of a bounded STDF V4 subset. `PASS` means the supplied observations fit this decoder and identity policy. It is not manufacturing acceptance, defect prediction, a process recommendation, or universal vendor compatibility. The example is original synthetic data, not a customer file.

Run `python3 product.py samples/valid.json OUTPUT_DIR`; exits are PASS 0, invalid FAIL 2, incomplete UNKNOWN 3. `bash SMOKE.sh` executes the unchanged manager acceptance gate. Python standard library only; no network, installation, customer accounts, or executable user input. `run`, `run_json`, `demo`, `bundle`, and `files_to_payload` are the browser adapter ABI. CPython tests are recorded in ACCEPTANCE.md; actual Pyodide/browser rendering is a separate integration check.

## Input

`input.schema.json` describes the envelope; `product.py` is the strict semantic validator. JSON duplicate keys, nonfinite numbers, excessive depth, boolean numeric settings, malformed base64, repeated source SHA256, and ambiguous file chronology are rejected.

A single payload is `{ "schema":"testlotreplay/v1", "stdf_base64":"...", "settings":{"identity":"part_id","rotation_degrees":0} }`.

For batch input replace `stdf_base64` with `sources:[{"filename":"a.stdf","order":0,"stdf_base64":"..."}, ...]`. `order` is a unique nonnegative integer; array order has no effect. Source order then PRR byte offset defines chronology. At most 32 sources, 8 MB combined binary data and 100,000 combined records/attempts. JSON nesting is limited to 24; maps show at most 2,000 resolved devices per lot/wafer, with all rows retained in CSV. Do not change period/file boundaries to hide a missing observation.

The two identity policies are `part_id` (lot + nonempty PART_ID; conflicting known locations refuse) and `wafer_coordinates` (lot + WIR wafer + signed X/Y through SDR site group). The declared schema default is `wafer_coordinates`. Empty identities or coordinate sentinel -32768 never collapse into a shared synthetic die. Supersession flags inconsistent with the selected identity policy make dependent metrics UNKNOWN. No guessed tester/site-to-wafer mapping is performed.

Rotation is absent or exactly 0, 90, 180, or 270 degrees counterclockwise in data coordinates (+X right, +Y up). Absent rotation is explicitly unspecified. WCR geometry is structurally decoded, but tester flat/orientation is never inferred into an equipment map.

## Actual local files

`files_to_payload` accepts a dictionary of basenames whose values are `{encoding:"utf8"|"base64",content:string}`. No paths are opened. Supported sets:

- Sole UTF8 `input.json` with the exact single or batch payload.
- Binary/base64 `input.stdf` plus optional UTF8 `settings.json` (settings object above). `samples/file-input/` contains real bytes; `example.stdf` is the downloadable synthetic binary.
- UTF8 `attempts.csv` plus optional settings, with exact unique header/order `lot,wafer,x,y,device_id,attempt_order,head,site,pass_status,hard_bin,soft_bin`. Order is globally unique within this normalized file; status is PASS/FAIL/UNKNOWN; numeric fields are canonical signed/unsigned integers, no units or floats. Empty coordinates/bins are unknown. This additional format never substitutes for the actual STDF workflow.

Unexpected filenames, paths, duplicate inputs, or simultaneous CSV/STDF refuse. To run normalized file ingestion in Python, call `files_to_payload(files)`, then `run` or `bundle`; the CLI consumes the resulting JSON.

## Binary support and refusal boundaries

FAR must be first, length two, STDF version 4, IEEE CPU type 1 (big endian) or 2 (little endian). VAX/other encodings refuse. MIR establishes lot; MRR terminates the file. Supported records: FAR 0/10, MIR 1/10, MRR 1/20, PCR 1/30, SDR 1/80, WIR 2/10, WRR 2/20, WCR 2/30, PIR 5/10, PRR 5/20, PTR 15/10. ATR 0/20 and BPS/EPS/DTR 50/10,20,30 are structurally checked non-yield text. All other records produce an explicit unsupported finding and withhold dependent aggregate metrics; no silent compatibility claim.

PIR/PRR episodes are keyed by HEAD_NUM and SITE_NUM. Missing or overlapping episodes, unfinished wafers/parts, truncated fields, count disagreement, missing MRR, unknown identity, aborted PRR bit 2 or invalid pass/fail bit 4 yield UNKNOWN. PRR bit 3 means failure only when pass/fail validity is known. Reserved bits or contradictory supersession flags refuse. First means the first observed attempt, final means the last observed attempt, including UNKNOWN; a later aborted attempt cannot reuse an earlier known pass.

PTR fields preserve test number/name, lot, head/site, source offsets, flags, scale and units. Descriptive values require explicit OPT_FLAG=0, result scale -18..18, nonempty units, finite result, and no unreliable/timeout/not-executed/aborted flags. The result is multiplied by 10^RES_SCAL. Implicit first-record/vendor defaults are not guessed: omitted/invalid scaling makes the file UNKNOWN. Test definitions with different lot/name/units/scale remain separate. Limits, Cpk, Gauge R&R and test pass/fail inference are outside scope.

## Output

Deterministic `result.zip` includes exact `input.json`, `report.json`, original binary sources under generated safe names, `README.txt`, `manifest.json` SHA256 content hashes, attempts/devices/transitions/bins/measurements/test summaries/source offsets CSV, policy, completeness, and first/final SVG maps separated by lot/wafer. `wafer-map.svg` is the first sorted lot/wafer group for compatibility; the HTML links every group. Unknown bundles contain observed evidence and null dependent totals, not final counts pretending completeness. CSV formula text is neutralized, numeric coordinates stay numeric.

`index.html` is a static escaped local viewer with native expandable first/final maps. No customer JavaScript executes. It uses the canonical USTA feeds shell and exact shared `styles.css`; its CSP disables remote resources including the canonical remote font, so offline Satoshi uses a local installation or the standard fallback. Report files are individually atomically replaced using unpredictable temporary names; this is not a two-file filesystem transaction. Package manifest hashes allow integrity checks after interrupted copies. No email or money action occurs.