--- title: "Timers and replay" url: https://services.dev/docs/service/timers captured: [time-three-ways.txt, time-tick.txt, time-timers.txt] --- # Timers and replay URL: https://services.dev/docs/service/timers > Every kind of time compiles to one timer on the record, keyed so a replay arms it again and no move of a date rewrites it. It is armed, fired, superseded or held, re-armed only by a closed list of events, committed once however often it is woken, and pinned with the bundle it was armed under. A timer answers one question: what is owed, and has it run? Every kind of time on [Keeping time](https://services.dev/docs/service/time.md) compiles to one, `tmr_…`, on the record. Each fires once for each time it is owed, in [the tick's](https://services.dev/docs/service/time.md#the-tick) order, under the version it was armed with, and the same way on a test clock as on the brand's own. ## Every timer is on the record | A timer | Holds | |---|---| | `key` | what it is, by [the grammar below](#the-key): `clk_8Tx1#US:rung:notice 90d:2027@0` | | `status` | `armed`, `fired`, `superseded` or `held`: [States](#states) | | `place` | its kind's place in the tick, 1 to 8 | | `owed_at`, `armed_at`, `fired_at`, `late_by` | when it was due, armed and run, and the gap | | `attempt`, `wakes` | how many times it proposed, and how many times it was delivered | | `version` | the bundle it was armed under: [Across versions](#across-versions) | | `commit` | the commit it made under its key; every later wake answers `replayed: true` with that commit | Every job, clock and subscription carries `next_timer`. `GET /timers?on=&status=`, `timers list --on`, `list_timers` and `timers.list()` read them. Acme's 2027 return, the day after it is minted: ```bash npx services.dev timers list --on job_4Tx9 --test-clock tc_7Hq4 ``` ```txt title="captured/time-timers.txt · magic values: none" job_4Tx9 · annual-return · period 2027 · on 2027-06 · at 2028-02-02 14:00Z · UTC · 4 fired · 1 held · 48 armed, the next 6 below id status owed fired place key tmr_9Tq1 fired 2028-02-01 14:00Z 2028-02-01 14:00Z 2 sbn_7Hq2:schedule:annual:2027 tmr_9Tq3 fired 2028-01-19 14:00Z 2028-02-01 14:00Z 6 clk_8Tx1#US-CA:rung:notice 90d:2027@0 tmr_9Tq5 fired 2028-01-19 14:00Z 2028-02-01 14:00Z 6 clk_8Tx1#US-NY:rung:notice 90d:2027@0 tmr_9Tq2 fired 2028-01-19 14:00Z 2028-02-01 14:00Z 6 clk_8Tx1#US:rung:notice 90d:2027@0 tmr_9Tq6 held — — 5 job_4Tx9:deadline:at_risk:2027 · held since 2028-02-01 14:00Z by ask_9Ts4 · 54d 10h 30m remaining tmr_9Tq4 armed 2028-02-15 14:00Z — 6 clk_8Tx1#US-NJ:rung:notice 90d:2027@0 tmr_9Tq7 armed 2028-02-15 14:00Z — 6 clk_8Tx1#US-TX:rung:notice 90d:2027@0 tmr_9Tq9 armed 2028-03-19 13:00Z — 6 clk_8Tx1#US-CA:rung:notice 30d:2027@0 tmr_9Tqb armed 2028-03-19 13:00Z — 6 clk_8Tx1#US-NY:rung:notice 30d:2027@0 tmr_9Tq8 armed 2028-03-19 13:00Z — 6 clk_8Tx1#US:rung:notice 30d:2027@0 tmr_9Tqc armed 2028-04-04 13:00Z — 6 clk_8Tx2:rung:notice 14d:2027@0 next_timer tmr_9Tq4 · 2028-02-15 14:00Z · the New Jersey notice, with Texas's at the same instant ``` One timer, whole: woken twice after a restart, committed once: ```txt → GET /timers/tmr_9Tq2 ``` ```json title="captured/time-timers.txt · 200 · tmr_9Tq2 · fired · magic values: none" { "id": "tmr_9Tq2", "object": "timer", "key": "clk_8Tx1#US:rung:notice 90d:2027@0", "on": "clk_8Tx1#US", "kind": "clock", "place": 6, "status": "fired", "version": "2027-06", "owed_at": "2028-01-19T14:00:00.000Z", "armed_at": "2028-02-01T14:00:00.000Z", "fired_at": "2028-02-01T14:00:00.000Z", "late_by": null, "attempt": 1, "wakes": 2, "commit": "evt_9Tr1", "superseded_by": null, "livemode": false } ``` ## The key A key is `:::[@]`. The occurrence is named by itself, never by its current date, so a date that moves or rolls never changes a key, and a replay arms the same keys: | Part | Is | apis.tax's | |---|---|---| | owner | the job, the clock occurrence or the subscription the timer belongs to | `job_4Tx9`, `clk_8Tx1#US`, `sbn_7Hq2` | | kind | `cycle`, `schedule`, `ask`, `task`, `deadline`, `rung`, `due`, `window` or `money` | `rung` | | name | the rung, the deadline's point, the schedule or the step | `notice 90d`, `at_risk`, `annual` | | occurrence | the period, the item or the cycle, by name | `2027`, `US-NY`, `#3` | | `@` | how many times the clock has moved, on a notice, escalate, ack or due timer | `@0`, then `@1` after the extension | A `run` rung leaves out `@`, so a move can never arm a second extension. Keys compare byte by byte, which settles the tick's last tie. ## States | Status | Holds | The runtime | |---|---|---| | `armed` | `owed_at` | fires at its owed time, in its place | | `fired` | `fired_at`, `commit` | done: every later wake answers `replayed: true` with the same commit | | `superseded` | `superseded_by`, `by` | replaced before it fired: a move, a repin or a policy change armed the successor `superseded_by` names | | `held` | `owed_at: null`, `held_since`, `held_by`, `remaining` | paused while the job waits on a party: the time left is kept, not spent | A held timer resumes under its own key at `resumed_at + remaining`. A date the world sets never waits: clock rungs are never held, and a deadline that follows a clock never moves its `late_at`. Only its at-risk timer is held, and it re-arms at the earlier of `resumed_at + remaining` and `late_at`; one whose time passed while it was held fires at resume, in place. Acme's at-risk timer, held from the mint by the organizer and resumed when the books arrive: ```txt → GET /timers/tmr_9Tq6 ``` ```json title="captured/time-timers.txt · 200 · tmr_9Tq6 · armed · magic values: none" { "id": "tmr_9Tq6", "object": "timer", "key": "job_4Tx9:deadline:at_risk:2027", "kind": "deadline", "place": 5, "status": "armed", "held_since": "2028-02-01T14:00:00.000Z", "held_by": "ask_9Ts4", "resumed_at": "2028-02-05T14:00:00.000Z", "remaining": "54d 10h 30m", "owed_at": "2028-03-31T00:30:00.000Z", "late_at": "2028-04-14T04:00:00.000Z" } ``` A [guarantee](https://services.dev/docs/service/clocks.md#price-a-missed-date) with `excludes: 'held'` reads the same state: time held on the client is never the brand's to pay for. A [deadline](https://services.dev/docs/service/within.md) pauses the same way. ## What re-arms a timer An armed timer re-arms only on one of these, recorded with what caused it: | On | The runtime | For example | |---|---|---| | `clock.moved` | supersedes each notice, escalate, ack and due timer still ahead and arms its successor at `@n+1`; the `run` timer keeps its key | the extension moves the federal date to 2028-10-16, and `notice 30d:2027@1` rings on 2028-09-16 | | `policy.set` | supersedes a `silent` timer and re-arms it from the last activity, with the new span | api.forsale's agent moves `stall_days` from 14 to 7: a deal whose account last replied on 3 November goes `gone_dark` on 10 November, not 17 | | a hold, and its resume | holds and resumes as [States](#states) says | the organizer waits on the books | | `calendar.postpone` | moves each clock it names, which re-arms as `clock.moved` | a disaster relief notice | | an edit to the calendar's `closed` days | re-rolls every date it touches: the calendar is never pinned | a closed day the IRS declares in March | | a commit that changes what a `due` read | runs `due` again; a new answer is `clock.moved { by: 'due' }` | a signed Form 872 sets `statute_extended_to`, and the assessment and refund dates move to it | | `clock.repinned` | re-arms the clock's timers under the newer bundle, superseding with `by: 'repin'` | a 2027-06 return joins Acme's subject | | `subscription.update` | re-arms the next mint with the new input; jobs already minted keep theirs | Acme adds Texas in March 2027 | Nothing else re-arms a timer; a deploy never does. ## After a gap After an outage, a deploy or a year's advance, every timer owed in the gap fires in the tick's order, each kind by its rule: | Kind | After a gap, the runtime | |---|---| | a schedule | mints each missed occurrence as its own period, and `period_taken` keeps each one once; [`catch_up`](https://services.dev/docs/service/subscriptions.md#after-a-gap) can mint only the latest | | clock rungs | sends only the latest owed notice or escalate rung, and records the earlier ones `superseded`; a `run` rung runs once | | `ack daily` | records each missed day | | a deadline | records at risk, then late, in order | | money | collects every owed line, in order | A timer more than 5 minutes late lists on the owner console with its `late_by`. One armed after its day fires at once and is never late. ## On a test clock A test clock, `tc_…`, is frozen at a time and moves only forward: | Call | Answers | |---|---| | `POST /test_clocks/:id/advance { to }` | 202 `advancing`, then `test_clock.ready` on the feed once every timer owed by then has fired | | `advance { to, redeliver: true }` | the same, with every wake delivered twice: each second one answers `replayed: true`, and nothing outside is sent twice | | an advance backward | 409 `test_clock_backward`, with the call that creates a clock there | | `DELETE /test_clocks/:id` | voids every job on it | | `tick 1y`, `tick --to