Actions + events

Business logic lives in actions; cross-cutting effects run through events. Controllers stay thin (policy → validate → action → response). Actions take a plain input, never HttpContext. When an action needs a side effect (mail, notification, transmit, external HTTP), it emits a domain event; a listener in the module's start/events.ts receives it and runs the effect. This keeps actions synchronous domain code, keeps side effects composable (a new listener is a new file, not an edit to the action), and makes testing effortless — fake the emitter, fake the mail.

Rules

• Location: app/<mod>/actions/<verb_noun>.ts — one file per action.
• Shape: default-export a class with a single public method async handle(input): Promise<Result | void>. input is a plain interface. No HttpContext.
• Return or throw: return the primary value (a model, an id, void). Throw domain exceptions from app/<mod>/exceptions/ for expected failure paths (rate limits, permission denials, invariant violations).
• Side effects go through events. Anything that reaches out is emitted, not called inline:

  emitter.emit('user:registered', { user, token })
  

  This applies to every kind of effect without exception: