# The nervous system

One channel. One kind of message. Anything that happens, a schedule coming due, a file changing, a peer reaching in, becomes a `SensorEvent` and goes onto the bus. Everyone listening hears all of it. No one waits on anyone else.

The code is `src/core/nervous/mod.rs`.

## The bus

`EventBus` is a broadcast channel, cloneable, so anything holding the server can subscribe and get its own stream. Two moves: `send` and `subscribe`.

Send is fire-and-forget. If no one is listening, or a listener has fallen behind, the event is simply gone. The bus is a nerve, not a ledger. Anything that must be kept subscribes and writes it down; the event log does exactly that.

The ring holds 256. A listener that falls further behind is told it lagged and skips ahead. Nothing is replayed.

That makes the bus unsuitable as belief or audit storage. Evidence that must
survive is accumulated by [belief](02-belief.md); state transitions and notable
somatic events that must be reconstructed enter the device forensic trail.

It is a broadcast and not a queue because many things want every event at once: the log, the heartbeat, the firehose, the federation bridge. A new listener, a desktop face, a health monitor, attaches without the sender ever knowing it is there.

## The message

Every event is a `SensorEvent`:

- `sensor_name`: who fired (`cron`, `energy`, `federation`)
- `event_type`: what it is (`schedule_due`, `sensorium:input`, `turn:segment`)
- `timestamp`: when
- `target`: a conversation, a schedule, a room; depends on the type
- `urgency`: 0 to 1, how loudly it asks to be seen
- `payload`: whatever the type needs
- `seed_id`: empty for a local event, a peer's key when it came from elsewhere
- `reply_to`: where a directed reply goes; empty for a broadcast

One type, not an enum per event, so a listener filters on `event_type` and ignores the rest, and the log can write everything down without knowing the taxonomy.

`seed_id` rides on every event though federation isn't here yet. When it lands, a sensor becomes federated without the envelope changing. See [federation/01-node-enrollment](../federation/01-node-enrollment.md).

## What pushes

A `SensorConfig` says how a sensor takes part: which domain (`Cron`, `Filesystem`, `FilesystemWatch`, `GitDiff`, `Memory`, `Process`, `Federation`), whether it pushes on its own or waits to be asked, when it fires (once, on change, or on an interval), and how eagerly.

A sensor marked as a nerve ending fires onto the bus uncalled. Right now the schedule is the only one that does. The other domains are named and waiting; nothing drives them yet. Tracked in `docs/tasks/firehose-subconscious-subscription.md`.
