Entropy Evidence Transport Contract

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

Implementation status (2026-07-19): target contract, not the current API. The current endpoint accepts EntropyIngestRequest with imageOpaqueRatio and layer ratio/byte totals and persists that snapshot for the ordinary scan-status response. The Worker emits entropy.report and entropy.layer-summary through Surface Manifest but has no client that posts them to this endpoint. The richer EntropyReportRequest, hash verification, replay attachment, and conflict semantics below remain unimplemented.

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.