docs(design): add user story knowledge bundle

2026-08-08 12:31:15 -04:00
parent baed3b4901
commit c76ea5b434
9 changed files with 198 additions and 0 deletions
@@ -0,0 +1,27 @@
+---
+type: User Story
+title: "US-005: Deliver events durably"
+description: Persist events locally and deliver ordered, bounded batches without blocking the Minecraft server thread.
+status: done
+---
+
+# US-005: Deliver events durably
+
+As a **server operator**, I want captured events buffered durably and retried after ingest failures so that temporary outages do not silently lose activity.
+
+## Acceptance criteria
+
+- [x] Events are persisted in an ordered local SQLite outbox before delivery.
+- [x] Persistence and HTTP delivery use dedicated workers rather than performing SQLite or network work on the Bukkit server thread.
+- [x] Delivery uses newline-delimited JSON batches bounded by configured event and byte limits.
+- [x] Delivery is requested periodically and may also be requested when an event-count or byte threshold is reached.
+- [x] Events are acknowledged and removed only after the ingest endpoint returns HTTP `202 Accepted`.
+- [x] Failed deliveries remain in the outbox and are retried with bounded exponential backoff.
+- [x] Stable event IDs provide at-least-once delivery semantics suitable for downstream deduplication.
+- [x] Shutdown waits for the shutdown event to be persisted and drains pending persistence work before closing the outbox.
+
+## Related
+
+- [US-001: Configure the event producer](us-001-configure-event-producer.md)
+- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
+- [Delivery and durability](../../README.md#delivery-and-durability)