Event Contract Matrix

A discipline for documenting who produces and who consumes each event in an event-driven or pub/sub system. It keeps the event contracts a single source of truth, so a change to a producer or consumer is visible against the whole graph instead of being discovered per call site.

The defining constraint: the matrix records the many-to-many relationship — each event lists its dispatch sites and its listeners — and explicitly notes sites that deliberately bypass the normal emit path. An event contract is not just "this event exists"; it is who can hear it.

What the matrix records

• One row (or entry) per event, listing:
  • the producer(s) that dispatch it — including any dispatch site that deliberately bypasses the standard emit path (e.g. containment-driven dispatch), so those are visible rather than a hidden surprise;
  • the listener(s) that receive it.
• The relationship shape: many-to-many, so the matrix is a table of event → producers and event → listeners, not one large implicit graph.

A dense many-to-many relation is best presented as a table rather than a sprawling graph — one event per row, producers and listeners as columns.

Keeping it a single source of truth