3.4 KiB
Phase 9: Faster Write-Back - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents. Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
Date: 2026-06-12 Phase: 9-Faster-Write-Back Areas discussed: Burst handling, Verification, Fallback interval
Burst handling
| Option | Description | Selected |
|---|---|---|
| Trailing re-drain (guarantee last edit) | If any signal arrives mid-drain, set drainRequested and re-run once the current drain finishes. Guarantees the LAST edit in a burst lands in ~1-2s. Slightly more CalDAV traffic under bursts. |
✓ |
| Short debounce/coalesce | Collect signals for a 200-500ms window and drain once. Gentler on Fastmail; last edit lands a fraction slower; adds a tunable knob. | |
| Fire-and-forget, rely on 15s for stragglers | Drop mid-drain signals; missed row waits for the next 15s tick. Simplest, but violates ~1-2s for the 2nd edit in a burst. |
User's choice: Trailing re-drain (guarantee last edit) Notes: Two-user household — burst volume is tiny, so snappiness/correctness of the trailing edit outweighs Fastmail request-rate politeness. Debounce knob rejected as premature.
Verification
| Option | Description | Selected |
|---|---|---|
| Automated integration test on the trigger | Vitest test asserting enqueue publishes the signal and runOutboxDrain fires promptly (mock CalDAV dispatch). Fast, CI-able, no live Fastmail. |
✓ |
| Both: integration test + operator stopwatch | Automated wiring test plus a one-time human checkpoint timing a real edit in the Fastmail native app. | |
| Operator stopwatch only | Human checkpoint timing real edit-to-Fastmail latency; nothing in CI guards regressions. |
User's choice: Automated integration test on the trigger Notes: Dev bypass user (id 1) has no CalDAV credential/calendars, so live event-create 422s in the dev stack — an automated wiring test is the durable, CI-guarded evidence. Real wall-clock latency is bounded by the CalDAV round-trip and exercised in production use.
Fallback interval
| Option | Description | Selected |
|---|---|---|
| Keep 15s | Leave the fallback at 15s exactly as today. Matches Success Criterion 5 wording; idle DB polling unchanged. | ✓ |
| Lengthen it (e.g. 30-60s) | Slow the fallback since the signal handles the hot path; fewer idle DB queries but slower recovery for missed rows; changes a number the criterion names. |
User's choice: Keep 15s Notes: Idle DB polling cost is negligible for this single-process, two-user deployment.
Claude's Discretion
- Exact shape of the
drainRequested/re-drain loop (flag location, loop insiderunOutboxDrainfinallyvs. scheduler wrapper) — left to planner/researcher, provided the no-double-drain guard and exactly-once guarantees hold. - EventEmitter singleton vs. tiny custom signal object — either acceptable; zero-dependency is the only hard constraint.
- Test file placement per existing convention (
apps/api/tests/, notsrc/).
Deferred Ideas
- Multi-process / multi-replica outbox drain via durable DB row-claim — out of scope while single-process; future scaling phase.
- Debounce/coalesce knob for burst write-back — considered and rejected for now; revisit only if Fastmail request-rate becomes a concern with more members.