# Streaming Framing Audit

Audit Server-Sent Events (SSE) streaming protocol compliance, chunk serialization overhead, heartbeat keep-alive frequency, and trailing metadata completeness (`data: [DONE]`).

## Workflow

1. Ingest recorded SSE stream metrics:
   - Total HTTP body bytes received ($B_{\text{wire}}$)
   - Useful payload character/token bytes ($B_{\text{content}}$)
   - Chunk count ($N$)
   - Heartbeat comments received (`: keep-alive` or `: ping`)
   - Max inter-chunk gap (milliseconds)
   - Proper terminal sentinel presence (`data: [DONE]`)
2. Compute framing overhead ratio:
   $$\text{Overhead Ratio} = \frac{B_{\text{wire}} - B_{\text{content}}}{B_{\text{content}}}$$
3. Verify heartbeat intervals: Ensure max quiet period does not exceed reverse proxy drop timeouts (e.g. 15–30s).
4. Assert zero JSON parse errors across all data chunks.

## Synthetic Input Format

JSON object with:
- `schemaVersion`: 1
- `endpoint`: string
- `streamTrace`:
  - `wireBytes`: positive integer
  - `contentBytes`: positive integer
  - `chunkCount`: positive integer
  - `heartbeatCount`: non-negative integer
  - `maxInterChunkGapMs`: positive integer or decimal
  - `hasDoneSentinel`: boolean
  - `malformedChunkCount`: non-negative integer
- `assertions`:
  - `maxOverheadRatio`: optional decimal string (e.g. "3.50")
  - `maxGapMs`: optional integer or decimal
  - `requireDoneSentinel`: optional boolean

## Exit Codes

- `0`: Valid trace and all streaming assertions passed.
- `1`: Assertion failure (missing done sentinel, excessive framing overhead, or timeout gap).
- `2`: Malformed input or safety violation.

## Verification

```sh
python3 scripts/check.py examples/synthetic.json
```
