event-driven-messaging

# Event-Driven Messaging Design for at-least-once delivery unless the complete system proves stronger semantics. ## Event contract - Use an immutable event envelope with `eventId`, `eventType`, `occurredAt`, `schemaVersion`, and payload. - Treat published schemas as APIs. Add fields compatibly and never silently change meaning. - Put correlation and causation IDs in headers or the envelope. - Do not publish JPA entities or framework-specific serialization shapes. ## Producer rules - Publish only after the originating state change is durable. - Use a transactional outbox when database state and broker publication must agree. - Use deterministic partition keys when per-aggregate ordering matters. - Configure delivery timeout and acknowledgements explicitly. ## Consumer rules - Make handlers idempotent with a durable processed-event record or naturally idempotent write. - Keep the transaction boundary around the state change and idempotency marker. - Classify transient and permanent failures before configuring retries. - Bound retries with backoff, then route poison messages to a dead-letter destination. - Preserve the original event, failure reason, and attempt count for replay. ## Testing - Test serialization compatibility and handler idempotency. - Use Testcontainers for broker integration tests. - Test duplicate, reordered, delayed, and poison messages. ## Examples - See `examples/good-consumer.java` and `examples/bad-consumer.java`. ## Gotchas - Agent assumes e...