Listeners — Concept

A listener is a rule that runs when an event is emitted during intent processing. It loads related entities via resolve: and applies mutate: ops — all before the commit completes.

Listener vs projection vs side_effects

	Listener	Projection	side_effects
Timing	Synchronous, same commit	Async via Kafka	After commit
I/O	None — entity mutations only	PostgreSQL UPSERT	emit, submit, schedule
Purpose	Cross-entity consistency in-process	Read models	Fan-out to other streams
Replay	Part of rule evaluation	Kafka replay	Re-submitted intents

When to use a listener

Update artist.follower_count when ARTIST_FOLLOWED fires — same commit as the follow intent
Apply scoring deltas to a match entity when POINTS_AWARDED fires
Keep two entity snapshots consistent without waiting for projection lag

When not to use a listener

Building a PostgreSQL table for the query service → projection
HTTP calls, external APIs, or fan-out to many entities → side_effects
Read-only analytics or dashboards → projection

Next steps

Defining Listeners — full syntax
Examples — concert and scoring YAML
Projection Examples — alternative async pattern for counters

Overview Defining Listeners