# Relay spawn tree (v3)

The tree is declared at init and never grows. Every thread is its own domain;
the only shared state between domains is a channel. There are two node kinds:
a **manager** owns children and is the interchange between them, a **worker**
does one job and talks only to its manager.

## Tree

```
root                        router + supervisor, no work beyond the gate
├── policy-manager          write ACL/allowlist, mute, blacklist, spam, free-write limiter
├── sig-manager             fan-out point for signature verification
│   └── sig-worker[0..M]    pure compute, one signature per request
├── network-manager         the relay proper: listeners, connection pool, live registry
│   ├── listener-worker[0..L]    owns the listening socket AND the accepted sockets
│   └── connection-worker[0..N]  multiplexer: per-connection protocol state, no sockets
└── database-engine         single writer and reader, owns time and truth
```

`L` = one per bind address. `N` = fixed connection-worker pool, connections
assigned by random selection. `M` = fixed signature pool, sized to saturate the
cores. Nothing is spawned at runtime in response to load; a crashed child is
respawned by its manager and its children come back with it.

## Who owns what

- **listener-worker** owns the socket, including every accepted socket and its
  poll registration. A *connection* is identified by remote IP:port. The
  listener reads wire frames, sends them up with their connection, and writes
  frames the manager hands it. It does no protocol work.
- **connection-worker** owns per-connection protocol state: frame parse and
  serialization, idempotence, per-connection limits. It holds no socket, no
  filter and no routing table.
- **network-manager** is the single authoritative subscription registry
  (`conn_id -> {sub_id -> filter}`) and the only node that matches events
  against filters. It knows which listener and which connection-worker each
  connection belongs to and forwards between them: wire frames up from the
  listener to the owning worker, delivery down from the worker to the listener.
  It holds no sockets and does no crypto or disk I/O.
- **root** routes and supervises. Inbound event: `Verify` to sig-manager first;
  on `VerifyResult{valid}` consult policy-manager, then `Persist` to
  database-engine and `Dispatch` to network-manager. It holds no durable state
  beyond the in-flight verification set.
- **database-engine** is the only node that touches disk, assigns the monotonic
  `seq`, and decides replaceable / parameterized-replaceable / deletion
  semantics atomically with the write. It owns its own clock and does periodic
  work (checkpoint, flush, compaction) on that clock, not on a command.

## Backpressure

A full channel stalls the sender until it clears: the buffer *is* the
backpressure. There is no drop-oldest and no unbounded queue. If the peer stays
unresponsive past the send retry window, the send fails; the manager treats that
as a dead child, respawns it, and everything in flight is lost. Delivery is only
ever attempted to a listener that is ready to write.

## Sequence and the history/live boundary

`seq` is the database's monotonic record, assigned to every stored event, and is
the seed of a Lamport-style clock for later sync protocols. `Dispatch` carries
it (0 = ephemeral, not stored). A REQ registers its filter with
`seq_floor = seq_high_water + 1`; stored events at or below that floor are
already accounted for by the history result and must not be delivered twice.
Ephemeral events are not stored, carry no seq, and are not subject to the floor.

Persisted events are dispatched after `PersistAck`, so a client that queries
immediately after publishing sees its own event.

## Flows

Ingest:
```
listener -> network-manager -> connection-worker -> network-manager -> root
root -> sig-manager -> sig-worker -> sig-manager -> root
root -> policy-manager -> root
root -> database-engine (Persist)      root -> network-manager (Dispatch)
network-manager -> connection-worker (match/format) -> listener (write)
```

Subscribe:
```
listener -> network-manager (register filter, seq floor) -> root -> database-engine
database-engine -> root -> network-manager -> connection-worker -> listener
```

## Invariants

1. No event is persisted or dispatched without a signature pass and a policy pass.
2. Only database-engine writes to disk.
3. Only network-manager owns live filter state.
4. Every domain has exactly one parent; crashes propagate down.
5. All children are spawned at init; the topology is static.
6. Connections are assigned to the worker pool by random selection.
7. One listener-worker per bind address.
8. Ephemeral events bypass persistence but not dispatch.
9. Storage is idempotent: the same event id is a no-op.

## Migration map (today -> v3)

| v3 node | today |
| --- | --- |
| root | server domain poll loop (`pkg/relay/server/server.mx`), which also parses, ACLs and ingests |
| policy-manager | inline in `pkg/relay/pipeline` and `pkg/relay/access` |
| sig-manager / sig-worker | none natively; `pipeline.StageA` runs inline; the browser has a verify pool in `web/static/wasm-host.mjs` |
| network-manager | `pkg/transport` + `Server.conns` + per-connection `c.subs` |
| listener-worker | none; transport accepts inside the same domain |
| connection-worker | none; one domain serves every connection |
| database-engine | `pkg/store` engine owned by the server domain |
| to delete | `wire.IngestWorker` (a second engine copy in a spawned domain), `wire.ProxyWorker`, `wire.BlossomWorker`, and the broadcast worker's ad-hoc fan-out |

The browser app mirrors the same nodes: page = root, relay-proxy worker =
network-manager, its client workers = connection-workers, the store worker =
database-engine, the verify pool = sig-manager/sig-worker.