feat(messaging): ADR-0030 P3b-1 — quiet-hours (deferred dispatch)

[os-zhuang]

Summary

Implements ADR-0030 P3b-1 — quiet-hours, continuing from merged P0–P3a. A notification that lands inside a recipient's quiet-hours window is deferred to the window's end instead of disturbing them; it then delivers normally.

P3b is split: P3b-1 (this PR) = quiet-hours (deferral); P3b-2 (next) = digest (window collapse), which builds on the same deferral foundation.

What changed (the elegant bit: reuse the P1 outbox)

No new scheduler, no parallel table — quiet-hours is a deferred dispatch on the existing outbox:

• EnqueueDeliveryInput.notBefore → the delivery row's initial nextAttemptAt. The P1 dispatcher already skips pending rows whose nextAttemptAt is in the future (memory-outbox/sql-outbox claim both check this), so the row simply isn't claimed until the window ends. One delivery spine, reusing claim / retry / dead-letter / observability.
• PreferenceResolver reads quiet_hours ({ tz, start, end } — P2's field) off a channel-wildcard preference row (quiet hours are a per-person, channel-agnostic setting), computes the deferral with quietHoursDeferral() (HH:MM in the row's tz, default UTC; overnight windows that wrap midnight supported; uses Intl for the tz wall-clock), and stamps notBefore on the target. emit() passes it through to enqueue.
• critical severity bypasses quiet hours (delivers immediately), mirroring how mandatory topics bypass muting. Honored on the durable outbox path; inline best-effort fan-out ignores it (quiet-hours needs the outbox).

Acceptance

• ✅ A notification inside the quiet-hours window is deferred to the window end (observable as the delivery row's next_attempt_at); outside the window it sends immediately; critical bypasses.

Testing

service-messaging: 92 passing — adds quietHoursDeferral unit cases (same-day / overnight-wrap / outside / degenerate / bad input) and resolver cases (notBefore stamped on target, critical bypass, JSON-string quiet_hours).

Follow-ups

• P3b-2 — digest: enqueue digest items deferred to the window, then a collapse step merges same-(user, channel, window) rows into one materialization at window time (needs a digest_key on the delivery row + a digest assembler + a digest render template). Consumes P2's digest field. Completes the ADR-0030 build spec.
• tz fallback to a sys_user timezone field (currently quiet_hours.tz → UTC).
• Still pending from P0: objectui bell cut-over + mark-read receipt write.

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 1, 2026 7:08am