Custom events & projections.

R5.01 taught the log as the source of truth and the fold as the rebuild. Custom events take that one step further: the events are not a fixed catalogue (placed, filled, closed), they are whatever the domain produces — a room opened, a guess scored, a game settled. Each event type gets its own named stream, so one log per channel keeps a reader from sifting unrelated entries. And a projection is a fold scoped to a slice of the log: take the entries in a time window and reduce them to exactly the shape one view needs — a per-room count, an hourly total, a running tally — recomputed from the log, never a separate table kept in sync.

Two moves carry the module, and they are two of the three dives. A custom event is a named stream: XADD <stream-name> … appends to a stream chosen by name, and the name is the domain-event channel. A projection is a windowed fold: read the slice of a stream between two instants and fold it to a read-model. The third dive is the discipline that keeps custom names safe — a stream's id field and a couple of key suffixes are reserved, and a custom event keeps clear of them.

A stream is identified by its key. Give each domain-event type its own key, and one append-only log per type follows: room-opened events go to one stream, guess-scored to another, game-settled to a third. A reader of the settlement feed reads only settlement entries; it does not page through guesses to find them. Adding a new event type is adding a new name — no schema migration, no shared table.

Each entry is immutable once written and carries a time-ordered id. The three streams are independent logs over the same instance; a projection reads one of them, or fans across several, and folds. The cost of one stream per type is a key per type; the buy is a focused log per feed.

A projection answers one question from the log: how many rooms opened this hour, what each player's running total is, which games settled today. It is a fold — start with an empty accumulator, apply each entry in order — scoped to a window of the log. The window is expressed in time, and time is an id range, because a stream entry id begins with the millisecond the entry was added.

Custom names are free, but a few are spoken for. The stream stores its canonical record id under a field named id, so a payload must not also name a field id — the reader would not be able to tell the stored id from the payload field. A key suffix is reserved for the archive watermark, so a stream's own name must not collide with it. And the whole keyspace is namespaced under a reserved prefix, so a custom stream lives inside that namespace rather than beside it.

The discipline is small and mechanical: keep custom event names and payload field names clear of the reserved few, and every other name is yours. The third dive, reserved-name discipline, takes it apart against the real EchoMQ surfaces.

Reach for custom events and projections when the domain produces many kinds of events and several views each need a different slice or shape of them: an activity feed, per-entity counters, time-windowed rollups, an audit that other readers also consume. One log per event type keeps each feed focused, and a projection per question keeps each read-model recomputable from the log.

Avoid a stream per event type when the events are few and one combined log reads fine — splitting then adds keys without buying focus. And a projection over a long window is work: where a rollup is read far more often than the window changes, fold once and cache the result, or trim the log to bound the replay (R5.02). A projection is recomputable, which is the point; recomputing it on every read when the inputs rarely change is waste.

EchoMQ's Stream Tier appends to a stream chosen by the caller. EchoMQ.Stream.append(conn, queue, name, fields) takes a name, mints an EVT-branded record id host-side, and issues XADD emq:{q}:stream:<name> <xadd_id> id <branded> <fields…> — so the name is the domain-event channel and the key is emq:{q}:stream:<name> via EchoMQ.Keyspace.queue_key/2. One brand per stream (EVT, the kind door in EchoMQ.Stream.Id) keeps the entry order, the id sort, and the mint order one and the same.

A projection is a windowed read folded to a read-model. EchoMQ.Stream.read_window(conn, queue, name, t0, t1, count) reads the closed [t0, t1] window, and EchoMQ.Stream.read_since(conn, queue, name, t0, count) the half-open [t0, ∞) window. Both derive the bounds host-side — minid_floor/1 turns t0 into "<ms>-0", maxid_ceil/1 turns t1 into "<ms>-<max-seq>" — so the wire only ever sees an <ms>-<seq> id and the window edges are exact. The returned {branded, fields_map} tuples are in mint order; fold them to the projection.

The worked consumer is codemojex — a Telegram emoji-guessing game on this stack (echo/apps/codemojex). Codemojex.Rooms.create_room/3 opens a room (a ROM), the first joiner starts a game (a GAM), Codemojex.Guesses.submit/3 enqueues a guess as a JOB on the player's PLR lane, and Codemojex.Scoring.score/2 scores it. Each of those lifecycle moments is a domain event appended to its own named stream; a windowed read of guess-scored folds to the live activity feed, and a read of game-settled folds to the day's results.

Each dive takes one move, in order: the named stream as a domain-event channel, the windowed fold as a projection, and the reserved-name discipline that keeps custom names safe. Read them in order — the channel first, the projection second, the discipline third.