# Architecture

## Objective

Turn a CSV of synthetic trade evidence into a machine-readable audit result without discretionary
human promotion.

```text
synthetic_trades.csv
        |
        v
schema and type validation
        |
        v
identity and chronology checks
        |
        v
PASS / FAIL / UNKNOWN
        |
        v
audit_report.json
```

## Evidence contract

Each row represents one completed synthetic trade and requires:

| Field | Contract |
|---|---|
| `trade_id` | non-empty and unique |
| `entry_time` | timezone-aware ISO-8601 |
| `exit_time` | timezone-aware ISO-8601 and not before entry |
| `side` | `-1` or `1` |
| `gross_return` | finite decimal |
| `cost_return` | finite and non-negative |
| `net_return` | `gross_return - cost_return` |
| `exit_reason` | non-empty |

## Fail-closed semantics

- `PASS`: all supplied evidence satisfies the contract.
- `FAIL`: supplied evidence violates at least one contract.
- `UNKNOWN`: no usable evidence exists.

`UNKNOWN` is never silently upgraded to `PASS`.

## Deliberate exclusions

The public package excludes:

- asset-specific features;
- entry or exit logic;
- parameter values selected from research;
- model weights;
- execution logic;
- portfolio allocation;
- broker connectivity;
- real market or account data.

The useful public asset is the **verification pattern**, not a decision rule.