# Findings Ledger Proxy Contract (Web V)

## Status
- Draft v0.1 (2025-12-01); to be validated at 2025-12-04 checkpoint with Findings Ledger Guild.

## Scope
- Gateway → Findings Ledger forwarding for vuln workflow actions (open/ack/close/export).
- Idempotency and correlation headers; retry/backoff defaults for offline-safe behavior.

## Required Headers
- `X-Idempotency-Key`: deterministic hash of `tenant + route + body`; required on POST/PUT; 36–64 chars; ledger must treat as unique for 24h TTL.
- `X-Correlation-Id`: UUID/ULID stable across gateway → ledger → notifier.
- `X-Stella-Tenant` / `X-Stella-Project`: tenant/project scoping per tenant-auth contract.
- `Authorization: Bearer <jwt>`: RS256/ES256 service token; `aud=stellaops-ledger`; scopes `ledger:write ledger:read`.
- `Content-Type: application/json`.

## Behavior
- Delivery semantics: at-least-once from gateway; ledger must guarantee exactly-once per `X-Idempotency-Key`.
- Retry/backoff (gateway):
  - Base delay 500 ms; exponential factor 2; jitter ±20%; max 3 attempts; cap total wait ≤ 10 s.
  - Offline kits: persist request NDJSON with headers; replay on next sync window.
- Timeout: 5 s per attempt; fail with `ERR_LEDGER_TIMEOUT`.
- Error mapping:
  - 400 series → `ERR_LEDGER_BAD_REQUEST` (propagate `details`).
  - 404 → `ERR_LEDGER_NOT_FOUND`.
  - 409 → `ERR_LEDGER_CONFLICT` (idempotency violation).
  - 429/503 → `ERR_LEDGER_RETRY`.
  - All responses include `trace_id` and echo `X-Correlation-Id`.

## Open Questions
- Confirm ledger idempotency TTL (proposed 24h) and whether ETag is returned for optimistic concurrency.
- Confirm expected payload schemas for each workflow action (open/ack/close/export).
- Confirm whether ledger enforces ordering per `tenant_id`.