--- title: "Clocks" url: https://services.dev/docs/service/clocks captured: [clock-calls.txt, clock-hard.txt, clock-moved.txt, clock-rungs.txt, grow-clock-tabs.txt, tax-cases.txt, tax-check.txt] codes: [clock_closed, clock_moved_on, clock_not_due, date_passed, evidence_required, evidence_used, ineligible, input_invalid, needs_the_owner] --- # Clocks URL: https://services.dev/docs/service/clocks > A clock is a date the world sets, beside the job's own deadline. It names who answers for it, rings rungs that give notice, escalate, ask for an acknowledgement and run a step through the gate, moves when an extension commits or never moves at all, can be one date per item, prices a miss, and never lapses silently. `clocks` answers one question: which dates does the world set for this work, and who answers for each one? ## Smallest form One line on the Translation from [A date the world sets](https://services.dev/docs/grow/clock.md). The registry takes the filing until a date the buyer names, and the buyer answers for it. Three days out, the clock asks for more time; at the date, unfiled, the buyer chooses. ```ts title="grow/clock.ts" file: { due: job => job.input.file_by, owner: 'buyer', rungs: ['run extend 3d'], moves: { extend: '14d after due' }, lapse: ['file', 'withdraw, in writing'] }, ``` It opens with the job, and every surface reads it: **CLI** ```bash title="CLI" npx services.dev clocks get clk_7Hq2 --json ``` ```txt title="captured/grow-clock-tabs.txt · magic values: none" "name": "file", "status": "open", "due_on": "2026-11-04", "type": "buyer", "rungs": [ "rung": "run extend 3d", "rings_at": "2026-11-01T00:00:00.000Z", ``` **API** ```bash title="API" curl http://localhost:8787/clocks/clk_7Hq2 ``` ```txt title="captured/grow-clock-tabs.txt · 200 · magic values: none" "name": "file", "status": "open", "due_on": "2026-11-04", "type": "buyer", "rungs": [ "rung": "run extend 3d", "rings_at": "2026-11-01T00:00:00.000Z", ``` **MCP** ```txt title="MCP" → tools/call get_clock {"id":"clk_7Hq2"} ``` ```txt title="captured/grow-clock-tabs.txt · magic values: none" "name": "file", "status": "open", "due_on": "2026-11-04", "type": "buyer", "rungs": [ "rung": "run extend 3d", "rings_at": "2026-11-01T00:00:00.000Z", ``` **SDK** ```ts title="SDK" await lingua.clocks.get("clk_7Hq2") ``` ```txt title="captured/grow-clock-tabs.txt · magic values: none" "name": "file", "status": "open", "due_on": "2026-11-04", "type": "buyer", "rungs": [ "rung": "run extend 3d", "rings_at": "2026-11-01T00:00:00.000Z", ``` ## Every form **On the Service** | Key | Written | Left out | Does | |---|---|---|---| | `clocks` | `{ : Clock }` | none | Dates the world sets, by name: when each is due, who answers for it, the rungs that notice, escalate, ask for an acknowledgement and run a step, the steps that move it, and what the owner chooses at the end. The rungs, moves, `every` and `on` run, and the clock's own calls acknowledge, satisfy, choose and name its owner. | | `calendar` | `Calendar` | the brand's | This Service's own calendar, in place of the brand's: its zone, closed days, closing minute and roll. | **Each clock** | Key | Written | Left out | Does | |---|---|---|---| | `due` | `((job) => string \| undefined) \| '${ClockSpan} after ${string}'` | required | The date: a function of the job returning a civil date (`'2027-04-15'`, closing at the calendar's minute in its zone, rolled past closed days) or an instant with its time, or nothing until the job has it; or a span after a step, an input or output date, an event, or another clock: `'365d after file'`, `'3mo after issued'`. With `each`, the function takes `(job, item)`. It reads only the job, never the wall clock or chance. A function that throws, or returns what isn't a date, records `clock.unopened` and `check` fails it as clock_due_unreadable. | | `each` | `{ of: }` | none | One occurrence per item, mirroring the step's `each`: `clk_…#US-NY`, moved and satisfied only by its own item's receipt. | | `owner` | `RoleWord \| 'brand' \| 'buyer' \| 'of_record'` | required | Who answers for it: a role, the brand, the buyer, or `of_record`, the member of record on the subject. One that resolves to no one leaves `owner` null, and the owner console alarms. | | `rungs` | `('notice ${number}d' \| 'escalate ${number}d' \| 'ack daily ${number}d' \| 'run ${string} ${number}d')[]` | none | Before due, in civil days, each ringing at the calendar's `rings_at`: `notice 30d` and `escalate 3d` tell the owner; `ack daily 7d` asks for an acknowledgement on each of the last 7 local days, and records each one missed; `run extend 3d` proposes the routed step `extend` through the gate 3 days out, once per occurrence; `'run extend 3d, again on move'` runs it after each move too. A proposal the gate holds or refuses stays armed, proposes again on each change to the record and each day at `rings_at`, and escalates to the owner at once. | | `lapse` | `( \| (string & {}))[]` | none | What the owner chooses at the due date, unsatisfied, through `POST /clocks/:id/choose`. A step's name runs that step, through the gate. Nothing lapses silently. | | `moves` | `{ [K in ]?: ((job) => string) \| '${number}${'d' \| 'w' \| 'mo' \| 'y'} after due' }` | none | Steps whose committed output moves the date, and to when: a function of the job, or a span after the date before any roll, `'6mo after due'`. Records `clock.moved`. | | `satisfied_by` | `[]` | its own name, when that is a step | The steps whose commit satisfies it, its output the evidence: a balance paid with the return closes the pay clock with `['pay', 'file']`. | | `every` | `Every` | none | Recurring: once satisfied, its next occurrence comes this far on, counted from the first so it never drifts, with its rungs. | | `lives_on` | `'job' \| 'subject'` | `'job'` | On the subject, so it outlives the job; or on the job. | | `roll` | `'none' \| 'next open day'` | the calendar's | `'none'` keeps a date that falls on a weekend or a closed day; else the calendar's roll. | | `hard` | `true \| { bars: ( \| '.' \| { step, when })[] }` | none: a step may move it | A date nothing moves but the calendar: `moves` is refused when the file loads. With `bars`, once the date passes unsatisfied, the gate refuses those steps, here or in another Service on the subject, with 409 `date_passed`. | | `exposure` | `(job, late) => number` | none | What a miss costs, in dollars, for the time `late`: printed in each rung's notice, sorting the owner console's dates at risk, and shown at the owner's choice. | | `guarantee` | `{ covers: ('penalties' \| 'interest on them')[]; up_to: number; after?: ; excludes?: 'held' }` | none | On a clock the brand or `of_record` answers for: a penalty for its period, with its interest when `covers` names it, is paid from your line up to `up_to`, once the `after` Service has asked for it to be taken off. With `excludes: 'held'`, time the work was [held](https://services.dev/docs/service/timers.md#states) on the client is left out. Records `guarantee.claimed`. | ## A date someone else set A clock is a date a registry, a regulator or a contract set, beside your own [deadline](https://services.dev/docs/service/within.md). It holds whether or not anyone works, and can outlive the job on its [subject](https://services.dev/docs/service/subject.md). ## Two dates, two clocks When two dates move differently, they are two clocks. A step that `moves` names moves only its own clock's date, counted from the date before any [roll](https://services.dev/docs/service/time.md#the-calendar), and a step `satisfied_by` names closes it with no one acting. After a move: | Rung | The runtime | |---|---| | notice, escalate, ack | each one still ahead is `superseded`, its `superseded_by` naming a successor armed for the new date at `@1`: the extended return hears `notice 30d` on 15 September | | `run` | keeps its key, which carries no `@`, so it runs once per occurrence and no second extension is filed; `'run extend 3d, again on move'` runs after each move | | a `due` function | runs again only after a commit changes what it read; a new answer records `clock.moved { by: 'due' }`, so a replay never calls it | ```bash npx services.dev tick 6mo --trace ``` ```txt title="captured/clock-moved.txt · magic values: none" tc_7Hq2 · 2027-04-15 12:00:00Z → 2027-10-15 12:00:00Z · UTC · 2 fired pass owed fired place kind on what 1 2027-04-15 23:59:00Z 2027-04-15 23:59:00Z 6 clock clk_7Hq3 pay · due 2027-04-15, unsatisfied · waits on the buyer's choice 1 2027-09-15 00:00:00Z 2027-09-15 00:00:00Z 6 clock clk_7Hq2 file · notice 30d · due 2027-10-15 · owner brand run extend 3d ran on 2027-04-12 for this occurrence: once per occurrence, so 2027-10-12 proposes nothing ``` ## A date for each item `each: { of: 'jurisdictions' }` gives one occurrence per item, each moved or satisfied only by its own receipt. On 11 July the 2026 return's federal, California and New Jersey dates close; New York's waits for its repair: ```bash npx services.dev clocks list --on job_4Tx3 --test-clock tc_7Hq4 ``` ```txt title="captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}" job_4Tx3 · annual-return · period 2026 · at 2027-07-12 09:00:00 · 7 clocks id name item status due moved from by clk_7Hq9#US file US satisfied 2027-10-15 2027-04-15 file · accepted 2027-07-11 clk_7Hq9#US-CA file US-CA satisfied 2027-11-15 2027-04-15 file · accepted 2027-07-11 clk_7Hq9#US-NJ file US-NJ satisfied 2027-11-15 2027-05-17 file · accepted 2027-07-11 clk_7Hq9#US-NY file US-NY open 2027-10-15 2027-04-15 rejected ein_mismatch 2027-07-11 · a repair by 2027-07-21 keeps 2027-07-11 clk_7Hqa pay — satisfied 2027-04-15 — pay · rcp_7HqB 2027-04-12 clk_7Hqb assessment — open 2030-07-11 — on the subject · the brand's · 3y after the filing clk_7Hqc refund — open 2030-07-11 — on the subject · mbr_8Ea1's seat of record ends with it ``` ## A date nothing moves Some dates never move: a call that closes, a time to pay, the last day a claim can be brought. `hard: true` says so, and `check` refuses a hard clock with `moves`. A grant application's call closes with `hard: { bars: ['lodge'] }`; the organisation signs a day late, so the gate refuses to lodge, and a charge waiting on lodge's receipt never releases: ```bash npx services.dev tick 6d --test-clock tc_7Hq6 ``` ```txt title="captured/clock-hard.txt · magic values: organisation.email = signs@example.test, metadata.sandbox.asks = {"approve":"after 5d"}" tc_7Hq6 · 2026-11-26 09:00:00 → 2026-12-02 09:00:00 · 8 fired · 2 acts 2026-11-28 00:00:00 job_7Hq2 clock closes · rung escalate 2d · owner buyer · the owner console lists it 2026-11-30 23:59:00 job_7Hq2 clock closes · due 2026-11-30 · hard · choose: withdraw, in writing · owner buyer 2026-11-30 23:59:00 job_7Hq2 clock closes · barred · lodge is refused from here on 2026-12-01 09:00:00 job_7Hq2 approve · Harbor Trust signs through its own link, a day late · committed 2026-12-01 09:00:00 job_7Hq2 lodge · refused · date_passed · closes passed 2026-11-30 23:59, and nothing moves it ``` | A hard date with | Once it passes, unsatisfied | |---|---| | `bars: ['lodge']` | the gate refuses those steps with 409 `date_passed` | | `bars: [{ step: 'amended-return.file', when: claimsRefund }]` | a step of another Service on the subject is barred too, only while `when` holds: an amendment that claims a refund is refused at once, nothing held, and one that owes more tax files | | no `bars` | it stays open: its exposure grows, and its owner chooses | | a [postponement](https://services.dev/docs/service/time.md#the-calendar) | the calendar moves it, the one thing that can | apis.tax's `refund` clock closes three years after filing, and bars an amendment only when it claims money back: ```bash npx services.dev jobs again job_4Tx2 --service amended-return change="a second credit" --test-clock tc_7Hq3 ``` ```txt title="captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}" × 409 date_passed · amended-return.file is barred: refund on job_4Tx2 closed 2029-04-17, and the amendment claims a refund (claimsRefund) · nothing held why 3y after the date it was due, 2026-04-15, rolled past a weekend and Emancipation Day; it was filed early, 2026-02-01 next the brand's console: a refund claim after its date is a question for a person · an amendment that owes more tax still files ``` ## Price a missed date | Key | apis.tax writes | The runtime | |---|---|---| | `exposure` | `exposure: lateCost`, half a percent of the unpaid tax a month | prints "about $324 a month if it's late" in each notice, sorts the console's dates at risk, and shows beside the owner's choice | | `guarantee` | `{ covers: ['penalties', 'interest on them'], up_to: 5_000, after: 'notice-response', excludes: 'held' }` | adds "or we pay the penalty and its interest, up to $5,000, after we ask the IRS to take it off" to the price sentence, and pays what the IRS keeps from your line, `guarantee.claimed`, AI and members' pay whole | ## The clock calls A clock is operable, not just an alarm. Its owner acknowledges, satisfies and chooses. Anyone else gets the owner's app as the next step, and a choice waits for the date: ```bash npx services.dev clocks ack clk_7Hq3 ``` ```txt title="captured/clock-calls.txt · magic values: member = mbr_lapsed_credential, member = mbr_eligible" lodge is the brand's, at its console. next hand http://localhost:8787/console to the person it asks docs http://localhost:8787/docs/errors/needs_the_owner # the buyer's choice opens at the date $ npx services.dev clocks choose clk_7Hq2 renew_late expires is due 2026-11-30: its owner chooses then. next npx services.dev clocks get clk_7Hq2 docs http://localhost:8787/docs/errors/clock_not_due ``` Each call names the occurrence it means by its `due`, so a call for a date the clock has moved past answers `clock_moved_on`, with the call for the one it is at. At the date, a step the options name runs, through the gate: ```bash npx services.dev clocks choose clk_7Hq2 renew_late ``` ```txt title="captured/clock-calls.txt · magic values: member = mbr_lapsed_credential, member = mbr_eligible" clk_7Hq2 · expires · due 2026-11-30 · buyer · chosen · chose renew_late ``` The brand closes its own date the same way, on evidence on the record. ## The vacancy alarm A clock whose owner resolves to no one has `owner: null`, and the owner console alarms until someone answers for it, even [between jobs](https://services.dev/docs/service/subject.md#every-open-clock-has-an-owner). `assign` takes only a member who holds the role's credential: [Dates at risk](https://services.dev/docs/operate/dates.md#a-clock-no-one-answers-for) runs one. ## What happens on its own Rungs count back from the date, each ringing at the calendar's `rings_at` on its day, in the clock's place in [the tick](https://services.dev/docs/service/time.md#the-tick). At the date, unsatisfied, the clock waits on its owner's choice. Nothing lapses silently: | On its day | The runtime | Event | Who hears | |---|---|---|---| | `notice 30d` | tells the owner, with the date and the ways to keep it | `clock.noticed` | the owner, in their app | | `escalate 3d` | tells the owner again and lists the clock on the owner console | `clock.escalated` | the owner and the console | | `ack daily 7d` | asks for the day's acknowledgement, and records it missed at the day's close | `clock.ack_due`, `clock.ack_missed` | the owner | | `run extend 3d` | proposes the routed step through [the gate](https://services.dev/docs/service/gate.md), which commits it like any other | `clock.ran` | the record | | the date, unsatisfied | waits on the owner's choice of `lapse` options, with its `exposure`; a hard date bars its steps | `clock.due`, `clock.barred` | the owner and the console | | a step it `moves` commits | moves the date and re-arms the rungs still ahead | `clock.moved` | the owner | ```bash npx services.dev tick 7d --trace ``` ```txt title="captured/clock-rungs.txt · magic values: none" tc_7Hq2 · 2026-11-20 12:00:00Z → 2026-11-27 12:00:00Z · UTC · 1 fired pass owed fired place kind on what 1 2026-11-27 00:00:00Z 2026-11-27 00:00:00Z 6 clock clk_7Hq2 expires · run extend 3d → extend proposed · committed · waits on person at file $ npx services.dev tick 4d --trace tc_7Hq2 · 2026-11-27 12:00:00Z → 2026-12-01 12:00:00Z · UTC · 5 fired pass owed fired place kind on what 1 2026-11-29 00:00:00Z 2026-11-29 00:00:00Z 6 clock clk_7Hq2 expires · ack daily 2d · acknowledgement due · owner buyer 1 2026-11-30 00:00:00Z 2026-11-30 00:00:00Z 6 clock clk_7Hq2 expires · ack daily 2d · acknowledgement missed · owner buyer 1 2026-11-30 00:00:00Z 2026-11-30 00:00:00Z 6 clock clk_7Hq2 expires · ack daily 2d · acknowledgement due · owner buyer 1 2026-11-30 23:59:00Z 2026-11-30 23:59:00Z 6 clock clk_7Hq2 expires · ack daily 2d · acknowledgement missed · owner buyer 1 2026-11-30 23:59:00Z 2026-11-30 23:59:00Z 6 clock clk_7Hq2 expires · due 2026-11-30 · choose: renew late, let it lapse, in writing · owner buyer ``` A run rung the gate refuses is held. It escalates to the owner at once, stays armed, proposes again each day, and at the date its step is the first option. [Grants and decisions](https://services.dev/docs/service/grants.md#asked-again) shows one held on a grant that ran out. ## In the apps | App | Shows | Acts | |---|---|---| | [Customer portal](https://services.dev/docs/app/buyers.md#dates-periods-and-allowances) | each clock under its job or subject: its date, its next rung, who answers for it, and the date it moved from | on a clock the buyer answers for: acknowledge, mark done, choose | | [Delivery portal](https://services.dev/docs/app/members.md#the-dates-they-answer-for) | Your dates: each clock the member answers for beside their Tasks' due dates, late first | the same three, on their own clocks only | | [Owner console](https://services.dev/docs/operate/dates.md) | only the dates that need you: vacant, held, escalated, hard, due unsatisfied, with the next 30 days | assign an owner; the brand's own: mark done, choose | ## Money and plan A clock moves no money by itself: what it runs, what its owner chooses, and a `guarantee` you carry do. A clock on the job runs on every plan, one on the subject on [Launch](https://services.dev/docs/money/plans.md#launch), and `guarantee` on [Team](https://services.dev/docs/money/plans.md#team). Every kind of time, by plan: [Keeping time](https://services.dev/docs/service/time.md#plans). ## Seven surfaces | Op | API | CLI | MCP | SDK | Site | Docs | App | |---|---|---|---|---|---|---|---| | `clock.list` | `GET /clocks`, `GET /owner/clocks` | `clocks list` | `list_clocks` | `clocks.list()` | | 1 error page | customer portal, owner console, delivery portal | | `clock.get` | `GET /clocks/:id`, `GET /owner/clocks/:id` | `clocks get ` | `get_clock` | `clocks.get()` | | 1 error page | customer portal, owner console, delivery portal | | `clock.ack` | `POST /clocks/:id/ack`, `POST /owner/clocks/:id/ack` | `clocks ack ` | never: only its owner acts; an agent reads it with get_clock and hands on the owner's app | `clocks.ack()` | | 4 error pages | customer portal, owner console, delivery portal | | `clock.satisfy` | `POST /clocks/:id/satisfy`, `POST /owner/clocks/:id/satisfy` | `clocks satisfy ` | never: only its owner acts; an agent reads it with get_clock and hands on the owner's app | `clocks.satisfy()` | | 6 error pages | customer portal, owner console, delivery portal | | `clock.choose` | `POST /clocks/:id/choose`, `POST /owner/clocks/:id/choose` | `clocks choose