Lucas BergerandClaude Opus 4.8
c7955a46b9
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
60 lines
3.4 KiB
Markdown
60 lines
3.4 KiB
Markdown
# 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.
|