# Stack

Runtime stack. Minimal dependencies.

## Layers

| Layer | Tech | Notes |
|---|---|---|
| Runtime | Python 3.13, asyncio, nats-py | same venv as nimmer-lib |
| State | PostgreSQL (Phoebe), psycopg2, asyncpg later | bare SQL; no ORM |
| Event bus | NATS VM 122, port 30000, JetStream | gates, actions, zone state |
| Edge API | FastAPI HTTP + native WebSocket | clients |
| Workflows | Python state machines, k8s pods | ephemeral probes |
| Harness host | omp --mode rpc JSONL | host, not brain |

## Two buses

- Internal: NATS.
- External: HTTP/WebSocket edge gateway.
- Gateway translates; runtime never speaks HTTP; clients never touch NATS directly.

## JetStream: replay, not truth

- register change stream: durable; restart rebuilds materialized register copy.
- cycle trail stream: retention-bounded; replay decision/cycle/escalation/spawn.
- durable consumers per client tier; each replays from its own sequence.
- retention limits are policy; truth is in Phoebe.

## Dependency budget

Allow: nats-py, psycopg2/asyncpg, fastapi, uvicorn, stdlib.
Refuse: Kafka, Redis, RabbitMQ, ORM now, second broker.
Every new dependency must state its `why` here.

Version: 0.2 | Updated: 2026-11-04