From dc50919de761198cc0a1204896a13909e77a3682 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 10 Jun 2026 15:08:35 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20add=20backlog=20999.13=20=E2=80=94=20re?= =?UTF-8?q?duce=20event=20write-back=20latency=20(outbox=2015s=20drain=20?= =?UTF-8?q?=E2=86=92=20event-driven)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .planning/ROADMAP.md | 19 +++++++++++++++++++ .../.gitkeep | 0 2 files changed, 19 insertions(+) create mode 100644 .planning/phases/999.13-reduce-event-write-back-latency-outbox-drain/.gitkeep diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index a13ac97..7460629 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -441,3 +441,22 @@ Plans: Plans: - [ ] TBD (promote with /gsd-review-backlog when ready) + +### Phase 999.13: Reduce event write-back latency to the calendar provider (outbox drain) (BACKLOG) + +**Goal:** [Captured for future planning] Calendar create/edit/delete writes are enqueue-only (`calendarOutbox`, 202 optimistic-accept; D-12/D-05 — no Fastmail call in the route) and flushed to Fastmail by `runOutboxDrain` on a **15-second `setInterval`** (`apps/api/src/broker/outboxWorker.ts`). So a change can take up to ~15s to land in Fastmail (and longer to reflect back in the app, which depends on the separate 5-min poller). Reduce that perceived sync delay so edits feel near-immediate. + +**Options to weigh when picking this up:** +- **Event-driven drain (preferred):** trigger an outbox drain immediately after a successful enqueue (in-process signal, or Redis pub/sub which is already available) so the write fires within ~1s instead of waiting for the next tick — keep the 15s `setInterval` as a fallback/retry sweep. Must preserve the existing per-row etag/412 handling and the rapid-successive-edit ordering (see outboxWorker comments ~L312 — each edit carries its enqueue-time etag). +- **Shorter interval:** simplest, but more idle DB polling; a floor (e.g. 3–5s) trades latency for load. +- **Faster read-back too:** the user also sees latency from the 5-min poller reflecting the change back. Consider invalidating/short-poll after a local write, or optimistic UI already covering it — confirm whether the perceived delay is the write (15s) or the read-back (5min). + +**Boundary:** the optimistic 202 + outbox durability design (create-before-delete, drain concurrency guard, fresh-etag-before-PUT) must be preserved — this is a latency tune, not a rewrite of the write path. + +**Context:** Surfaced 2026-06-10. Tags: calendar, write-back, outbox, latency, redis, performance. +**Requirements:** TBD +**Plans:** 0 plans + +Plans: + +- [ ] TBD (promote with /gsd-review-backlog when ready) diff --git a/.planning/phases/999.13-reduce-event-write-back-latency-outbox-drain/.gitkeep b/.planning/phases/999.13-reduce-event-write-back-latency-outbox-drain/.gitkeep new file mode 100644 index 0000000..e69de29