# Entropy Evidence Transport Contract

Purpose: unblock SCAN-ENTROPY-186-012 by defining worker → webservice transport for entropy reports.

## Endpoint
- `POST /api/v1/scans/{scanId}/entropy`
- Headers: `X-Tenant-Id`, `Content-Type: application/json`
- Body: `EntropyReportRequest`

## EntropyReportRequest (JSON)
- `subject_digest` (string, required) — image digest.
- `report_path` (string, required) — relative path inside replay bundle (e.g., `artifacts/entropy.report.json`).
- `hash` (string, required) — SHA256 hex of the report file.
- `penalties` (object) — `{ overall: number, layers: [{ digest, score, high_entropy_regions: [ { offset, length, reason } ] }] }`.
- `created_at` (string, ISO-8601 UTC).
- `tool`: `{ id, version, rng_seed, max_parallel }`.

## WebService behavior
- Validate tenant, scanId, subject_digest matches scan record.
- Validate SHA256 by re-reading report from bundle if available; else accept hash and queue verification job.
- Persist entropy metadata with scan record and attach to replay manifest.
- Respond `202 Accepted` with `{ status_url }`; return `409` if entropy already recorded for scanId+subject_digest.

## Error handling
- `400` malformed request; `401/403` auth; `404` scan not found; `422` hash mismatch; `500` transient CAS/read errors.

## Determinism
- No clocks added server-side; use provided `created_at`.
- No recalculation of entropy; only verification.
- Log deterministic reasons for rejection to aid reproducible replay.