prep docs and service updates

docs/modules/findings-ledger/prep/ledger-attestations-storage.md

@@ -0,0 +1,54 @@
+# Ledger Attestations Storage & Query Contract (LEDGER-OBS-54-001)
+
+Status: PrepComplete (2025-11-20)
+Owners: Findings Ledger Guild · Provenance Guild
+
+## Goal
+Provide a deterministic storage/view contract so the `/v1/ledger/attestations` endpoint can be implemented without further design work.
+
+## Table (proposed)
+- Name: `ledger_attestations`
+- Partitioning: tenant-scoped (same strategy as `ledger_events`).
+- Columns:
+  - `tenant_id` (text, not null)
+  - `attestation_id` (uuid, not null)
+  - `artifact_id` (text, not null) — OCI digest or SBOM id
+  - `finding_id` (text, null)
+  - `verification_status` (text, not null; `verified|failed|unknown`)
+  - `verification_time` (timestamptz, not null)
+  - `dsse_digest` (text, not null; lowercase sha256)
+  - `rekor_entry_id` (text, null)
+  - `evidence_bundle_ref` (text, null)
+  - `ledger_event_id` (uuid, not null) — source ledger event linking the attestation
+  - `recorded_at` (timestamptz, not null)
+  - `merkle_leaf_hash` (text, not null)
+  - `root_hash` (text, not null)
+  - `cycle_hash` (text, not null)
+  - `projection_version` (text, not null)
+
+## Indexes / ordering
+- PK: `(tenant_id, attestation_id)`
+- Paging index: `(tenant_id, recorded_at, attestation_id)` to back deterministic sort `recorded_at ASC, attestation_id ASC`.
+- Lookup indexes:
+  - `(tenant_id, artifact_id, recorded_at DESC)`
+  - `(tenant_id, finding_id, recorded_at DESC)`
+  - `(tenant_id, verification_status, recorded_at DESC)`
+
+## Query contract for `/v1/ledger/attestations`
+- Filters map to indexed columns: `artifactId`, `findingId`, `attestationId`, `status`, `sinceRecordedAt`, `untilRecordedAt`.
+- Pagination token encodes `{ recordedAt, attestationId, filtersHash }`; server must reject mismatched hash.
+- Response fields align 1:1 with columns above; no joins required.
+- Determinism: sort strictly by `(recorded_at ASC, attestation_id ASC)`; no server clocks in payload.
+
+## Migration notes
+- Add table and indexes in the same migration (see `src/Findings/StellaOps.Findings.Ledger/migrations/004_ledger_attestations.sql`).
+- Backfill from existing provenance/verification store (if present) into this table with recorded_at = original verification timestamp.
+- Ensure writes/coalescing happen via ledger projections to keep `ledger_event_id`/`cycle_hash` consistent.
+
+## Observability
+- Logs: `ledger.attestations.query` (tenant, filtersHash, limit, duration_ms, result_count).
+- Metrics: `ledger_attestations_queries_total{tenant,status}`, `ledger_attestations_failures_total{reason}`; reuse endpoint spans already defined in prep doc.
+
+## Artefact location
+- Storage contract: `docs/modules/findings-ledger/prep/ledger-attestations-storage.md`
+- HTTP contract: `docs/modules/findings-ledger/prep/ledger-attestations-http.md`