familysync/.planning/milestones/v1.1-phases/09-faster-write-back/09-DISCUSSION-LOG.md

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 inside runOutboxDrain finally vs. 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/, not src/).

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.