# Findings Ledger OAS baseline (v1)

**Scope.** Establish the canonical OpenAPI baseline and API host definitions for Findings Ledger. This satisfies PREP-LEDGER-OAS-61-001 and unblocks downstream OAS/SDK/OBS tasks (61-002..63-001).

**What shipped (2025-11-20).**
- Published baseline OAS document: `docs/modules/findings-ledger/openapi/findings-ledger.v1.yaml` (OpenAPI 3.0.3).
- Servers: `https://{env}.ledger.api.stellaops.local` (env ∈ dev/staging/prod/airgap) and offline `https://ledger.{region}.offline.bundle`.
- Security: `bearerAuth` (JWT) and `mTLS` declared; tenant header `X-Stella-Tenant` required.
- Paths included:
  - `GET /v1/ledger/events` (deterministic paging by chain/sequence; cursor header).
  - `POST /v1/ledger/events` (append; validates hashes; 409 on non-deterministic input).
  - `GET /v1/ledger/projections/findings` (projection read with `cycleHash`).
- Schemas align with `docs/modules/findings-ledger/schema.md` (ledger events, projections, hashes, provenance fields).

**Usage / next steps.**
- Export to renderer or client generation from `findings-ledger.v1.yaml`; keep schema source of truth in YAML, not code-first.
- Downstream tasks (61-002, 62-001, 63-001) should extend this spec with SDK/validation/deprecation headers but **must not** change base paths, security schemes, or canonical field names.
- When new fields are added, update both `schema.md` and the YAML and bump `info.version` with changelog entry.

**Determinism & offline posture.**
- Stable ordering: events sorted by `(chainId, sequence)`; projections do not perform consensus/merges.
- No external calls required at runtime; offline host is declared for bundle deployments.
- Hash fields (`eventHash`, `previousHash`, `merkleLeafHash`, `cycleHash`) remain lowercase hex SHA-256 per schema.

**Artifact locations.**
- OAS YAML: `docs/modules/findings-ledger/openapi/findings-ledger.v1.yaml`
- Schema reference: `docs/modules/findings-ledger/schema.md`
- Export surface reference (for later OAS extensions): `docs/modules/findings-ledger/export-http-surface.md`