up the blokcing tasks

docs/modules/scanner/design/entropy-transport.md

@@ -0,0 +1,30 @@
+# 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.