Notification delivery defers to recipient-local quiet windows resolved from stored timezone and policy, with audited urgent overrides and bounded hold queues so marketing sends cannot bypass sleep hours without an explicit break-glass path.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Each recipient carries a resolved IANA timezone and a quiet-hours policy defined in delivery-window.yaml as the authoritative schedule source. example.yaml references that schedule rather than duplicating conflicting times. Non-urgent notifications scheduled during quiet hours enter a hold queue and deliver at the next permitted open time unless an audited urgent override applies. Marketing-blocked classes cannot use urgent override paths reserved for security, account-recovery, or payment-failed categories.
Scope
- Recipient timezone storage, quiet window evaluation, deferral queues, and urgent override audit trail.
- Email, push, and in-app channels covered by the profile policy table.
- Re-evaluation when users update timezone or quiet-hour preferences, including DST gap and overlap handling.
Outside this block
- Template rendering and localization of notification body content.
- Provider-specific deliverability tuning for email IP reputation.
- Legal quiet-hour statutes; adopters map jurisdiction requirements into their own policy tables.
Contract
delivery-window.yamlis authoritative for schedule windows, urgent_classes, and marketing_blocked_classes; example profile fields must reference or mirror it without drift.- Quiet evaluation uses the recipient stored timezone at scheduling time; if timezone is unknown, the profile default timezone applies and is flagged on the delivery record.
- Non-urgent messages attempted during quiet hours receive state
deferred_untilwith an ISO timestamp at the next open boundary. - Urgent overrides deliver immediately only when the message class appears in urgent_classes with allowed_during_quiet true and an audit record is written before send.
- Classes listed in marketing_blocked_classes cannot override quiet hours.
- Hold queue depth per recipient is bounded; when exceeded, oldest deferrable marketing messages expire with auditable drop reason.
- Timezone updates requeue pending deferred messages using the new local open time within the profile recomputation SLA.
- DST gap and overlap handling follows dst_policy; ambiguous local times must not cause early delivery.
Implementation guidance
- Evaluate quiet windows in the orchestration layer before provider dispatch, not inside each provider adapter.
- Validate profile imports against delivery-window.yaml on deploy.
- Use deterministic open-boundary calculation tested against DST transition dates relevant to the product user base.
Failure handling and safeguards
- Clock skew between schedulers must not deliver early; use coordinated UTC storage with local conversion at evaluation.
- If hold queue persistence fails, fail closed by deferring rather than sending during quiet hours.
- Misconfigured timezone strings reject at profile save with validation errors.
Verification and operations
- Tests cover deferral, override audit, marketing block, DST spring-forward gap, fall-back overlap, and schedule authority checks.
- Metrics include deferred volume, override rate by class, and hold-queue saturation events.
Adoption assumptions
- Names and numeric values in
example.yamlanddelivery-window.yamlare an adoption profile, not universal defaults. - The adopting team maps legal marketing curfew requirements into policy tables without this block asserting compliance.