docs/ARCHITECTURE.md

# rosie — Executive Operator — Architecture

> 5-organ fusion + GO/REVIEW/NO-GO + deterministic replay

## Investor summary

This organ is one node of the SZL multi-organ AI mesh. It exposes a small set of
named, versioned HTTP endpoints, signs a Khipu receipt for every consequential
action, and is grounded in Lean-verified anchors (Doctrine v11 LOCKED: 749
declarations / 14 axioms / 163 tracked sorries; Λ remains **Conjecture 1**, not a
theorem — stated honestly).

## Module layout (named, investor-grade)

The runtime is composed of named modules, each with a single responsibility:

- **app / serve** — FastAPI app + route table (the front door).
- **api (v4)** — versioned API surface; the live moment endpoint is `/api/rosie/v4/orchestrate`.
- **web** — HTML operator surfaces (`/operator`, `/demo`).
- **policy** — Lean kernel + Khipu + fail-closed gates (Doctrine v11 LOCKED).
- **voters** — LLM voter modules (ensemble vote; the SZL moat).
- **provenance / dsse** — Cosign/DSSE signing of every receipt.
- **tests** — pytest suites.
- **docs** — this investor-facing documentation.
- **.compliance** — SLSA, SBOM, and Section 889 attestations.

> Repo hygiene note: the production Dockerfile uses explicit per-file `COPY` for
> the runtime modules (not `COPY . .`). To stay strictly ADDITIVE and never break a
> live route, this cleanup adds named documentation and compliance folders rather
> than physically relocating runtime modules that live routes depend on.

## Signing & verification

Every receipt is a DSSE envelope. Verify with cosign:

```bash
cosign verify-blob --signature <sig> <receipt.json>
```

Real ECDSA-P256 signatures are emitted only when the `SZL_COSIGN_PRIVATE_PEM`
runtime secret is present; otherwise receipts are honestly labelled UNSIGNED.

## Cite

Zenodo concept DOI: [10.5281/zenodo.19944926](https://doi.org/10.5281/zenodo.19944926).
Grounded in: Hickok & Poeppel 2007 · Hickok 2025 *Wired for Words*.