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.

Safe Subscriptions

• Convert the RxJS stream behind

  EventBus

  into signals at the Application boundary using

  toSignal()

  before exposing data to Presentation stores.
• Guard subscriptions with

  takeUntilDestroyed()

  or signal-based cleanup so that event handlers do not leak after a component/store is destroyed.
• Prefer

  @ngrx/signals

  stores for reacting to events; their

  withMethods

  handlers should call

  patchState

  based on event payloads rather than mutating the store directly.

Validation & Monitoring

• Validate payload schemas before append, using domain value objects to enforce invariants (Domain layer) and rejecting invalid data early.
• Emit audit events when Append or Publish steps fail so

  docs/AUDIT-*

  trackers capture the problem context.
• Feed causality IDs into any observability tooling to verify the Append→Publish→React chain during CI or runtime tracing.