# Event Contract Baseline

Purpose: define stable event contracts for PubSub, WebSocket pushes, and Broadway pipeline messages.

---

## Contract Source of Truth

1. AsyncAPI or equivalent schema files are the source of truth for event names and payloads.
2. Event producers and consumers must version payloads explicitly.
3. Event changes must preserve backward compatibility unless a major version is introduced.

Recommended location for source files:
- contracts/asyncapi/mw_core.events.v1.yaml

---

## Required Event Topics (Phase 2-4)

| Topic | Producer | Consumer | Delivery Type |
|-------|----------|----------|---------------|
| jobs:{job_id} | infra_queue | gateway_ws, gateway_mobile | at-least-once |
| transactions:{tx_id} | adapter_banking | gateway_ws | at-least-once |
| system:notifications | mw_router, infra_telemetry | gateway_ws | best-effort |
| route_table:updated | mw_router | all nodes | at-least-once |

---

## Payload Contract Rules

1. Every payload must include:
- event_name
- event_version
- trace_id
- emitted_at
2. Sensitive data must be redacted before publish.
3. Unknown fields must be ignored by consumers for forward compatibility.

---

## DLQ Contract

Failed async messages must include:
- source_pipeline
- original_payload_sanitized
- error_code
- retry_count
- first_failed_at
- last_failed_at

No cardholder data or secrets are allowed in DLQ payload storage.

---

## Validation in CI

1. Validate event schema file syntax.
2. Run producer contract tests for topic + payload shape.
3. Run consumer compatibility tests on sample payload fixtures.

---

## Ownership

- Platform Team: topic lifecycle and reliability semantics.
- Gateway Team: WebSocket delivery contract.
- QA Team: consumer compatibility tests.