0016. Time-based triggers: types, fire index, fire keys, timezones, and activation confirmation
- Status: Accepted; the activation confirmation token is superseded by 0033
- Date: 2026-11-08
Context
Section titled “Context”Time-based triggers are in the MVP (ADR 0015). They must fire without scanning every customer, must not fire an occurrence twice across retries, republishing, or timezone changes, and must behave predictably across DST changes on both targets. A spike (2026-11-07) compared Intl time-zone output for 9 zones over 2025–2027 in workerd and Node 22, 24, and 26: the transitions were identical, but the bundled tzdata versions differ.
Decision
Section titled “Decision”Trigger types (part of the versioned workflow definition, validated when a version is saved):
| Type | Example definition | Fires |
|---|---|---|
attribute_date |
{attribute: "trial_ends_at", offset: "-P3D", local_time: "09:00", timezone: "customer", catch_up: "PT24H"} |
Once per customer per attribute value; rescheduled when the attribute changes; cancelled when it is cleared or the customer is deleted |
schedule |
{rrule: "FREQ=WEEKLY;BYDAY=MO;BYHOUR=9;BYMINUTE=0", timezone: "customer", audience: <condition>, catch_up: "PT6H"} |
Each occurrence starts runs for the audience at that occurrence |
once |
{at: "2026-12-01T09:00", timezone: "project", audience: <condition>} |
One occurrence, then the trigger is done |
Schedule format:
- A constrained RFC 5545 RRULE subset:
FREQDAILY, WEEKLY, or MONTHLY, withINTERVAL,BYDAY,BYMONTHDAY,BYHOUR, andBYMINUTE. - Validation computes occurrences and rejects any rule with more than one occurrence per local day. This closes the loophole of a daily rule with several
BYHOURorBYMINUTEvalues. timezoneiscustomer,project, or an IANA zone.customerreads the customer’stimezoneattribute and falls back to the project timezone when it is missing or invalid.
Scheduling:
attribute_datekeeps a per-customer fire indextrigger_fires(trigger_id, customer_id, occurrence_key, fire_at), updated in the same transaction as the customer change and backfilled in batches on activation.scheduleandoncekeep one slot per trigger and timezone bucket,schedule_slots(trigger_id, tz, fire_at, cursor).- At an occurrence, the audience is snapshotted at the occurrence time and drained in bounded batches with a saved cursor; customers who match only later are not added. Eligibility is still rechecked before each send.
- A per-occurrence recipient cap applies. An occurrence whose audience exceeds the cap does not fire; it is logged and the owner is notified.
- Fire rows store the nominal local time, the timezone, and the tzdata version used.
- A change to a customer’s timezone invalidates and recomputes that customer’s fire rows.
- Index rows and slots carry a generation tag of the trigger version they were computed from; rows with a stale generation are ignored and recomputed.
- The same core
tickdrives both targets: the DO alarm on Cloudflare, theschedulerservice in containers.
Fire keys and run identity:
- A time-triggered run’s ID is
hash(project, workflow_id, trigger_step_id, customer_id, occurrence_key). occurrence_keyis the nominal occurrence (forattribute_date, the attribute instant plus the offset; forschedule, the local nominal date-time; foronce,at). It contains no version and no timezone, so republishing or a timezone change cannot fire the same occurrence twice.
DST and missed fires:
- Occurrences are computed in local wall time with runtime
Intl. Temporal is not used. - A skipped local time (spring forward) shifts to the first valid instant; a repeated local time (fall back) uses the first instant.
catch_updefaults to 24 hours forattribute_dateand 6 hours forschedule. A late fire within the window runs and logslate_by; otherwise it isskipped:missed_window. After an outage, missed recurring occurrences collapse into the latest one.- A fire time already in the past when the attribute is set or the trigger is activated follows the same rule.
- The Node container image pins its Node version and is rebuilt on Node patch releases. A golden-file timezone contract test runs on both targets in CI, and a weekly job runs it on the latest runtimes.
Actions and confirmation:
workflows.preview_triggers(read-only) returns the next fire times per timezone bucket, affected customer counts, timezone fallbacks, DST adjustments, past-due skips, and a short-lived confirmation token bound to the version hash.workflows.activateof a sending workflow requires that token. This is the server-side confirmation mechanism for activation that ADR 0005 left open.workflows.list_upcoming_firesanswers “when will X be sent”.runs.testaccepts a simulated time or the next occurrence and uses the injected clock.
New step-log reasons: skipped:missed_window, skipped:audience_condition_false, skipped:attribute_cleared, skipped:recipient_cap.
Consequences
Section titled “Consequences”- Recurrences more frequent than daily need a new ADR with a cost review.
- A tzdata difference between runtimes shows up as a golden-file failure, not as a wrong send.
- Stop and version-change behaviour for pending fires is in ADR 0017.
Amendment (2026-11-18, ADR 0044, decided by the maintainer): the send approval that replaced this ADR’s confirmation token is required only in workspaces that turn it on; it is off by default. Where it is off, a time-triggered sending workflow goes live without a confirmation; workflows.preview_triggers stays a read-only preview, and the per-occurrence recipient cap stays.
Amendment (2026-11-19, ADR 0041): there is no owner role. The notice of an occurrence over the recipient cap goes to the workspace’s admin users.
Amendment (2026-11-19, pending ADR 0045, ADR 0049, and ADR 0050, Proposed): a trigger’s audience uses the condition language of ADR 0045, may reference a saved audience ({ inAudience }, expanded into the version at save), and may be set on every trigger type; for event and attribute_date it is checked for the one customer when the trigger fires. A once trigger at “now” fires at the next tick (ADR 0049). A confirmation token returns in ADR 0050’s form, on the committing action; workflows.preview_triggers stays read-only and its content is part of that preview. The per-occurrence recipient cap remains what bounds each occurrence. The snapshot rule above is amended (ADR 0045): the drain considers only customers created by the occurrence time and evaluates each on their data when the cursor reaches them, because the store keeps no attribute history; a customer whose data changes between the occurrence and the drain is judged on the new values.