Eventing Hub Master Guide

Intent

Describe event contracts, persistence/publish order, and consumer safety for the shared EventBus described in src/app/eventing/AGENTS.md and .github/instructions/20-ddd-event-sourcing-copilot-instructions.md.

Event Schema

• Declare events with a Type, Payload, Metadata, and Semantics structure; keep payloads immutable and document any allowed mutations in the metadata.
• Use a correlationId to tie related events, and assign a causationId that points to the triggering event (null only for root events).
• Emit only typed events from the Aggregates/Application services; do not publish raw DTOs or Firebase objects.

Append → Publish → React

• Persist every outcome (Append) before invoking the EventBus publish step; never wrap append/publish in Promise.all or parallel flows to avoid causality gaps.
• After the append promise resolves, publish the event and let downstream stores/projections react via the global EventBus singleton.
• Reactions should be limited to simple projections or side effects; long-running work belongs to dedicated use cases handled by the Application layer.

Causality Tracking & Immutability

• Maintain causation/correlation IDs for every published event; log them for tracing and include them in metadata for audit tooling.
• Treat emitted events as read-only facts; consumers may inspect but must never mutate payload or metadata objects.
• Use Object.freeze() or deep copies when broadcasting to ensure immutability guarantees reach all subscribers.