Scheduling
Standing cron, interval, and one-shot schedules whose exactly-once fires enter the lineage as ordinary observations, so the lineage stays the only source of truth.
The workspace scheduler lets an app declare standing schedules (cron calendars, fixed
intervals with every, and one-shots with at) that deterministically append schedule
fire observations into a lineage. The scheduler is only an input authority. It does not
derive facts, create intents, or execute effects. A schedule such as “every weekday at
09:00, refresh the feed” goes through the same pipeline as every other observation:
schedule fire observation → mapper atoms → rules → intent.* → declared effect capability
Fire observations
Fires arrive as schedule.tick observations (reserved source capability:scheduler)
carrying the schedule id and digest, the scheduled_for instant, the fire kind
(occurrence, catch_up, or manual), DST and catch-up metadata, the timezone-database
version, and your declared payload under data.
Occurrence identity is (lineage_id, schedule_id, scheduled_for), and each fire is
appended through the idempotent observation contract. Crash recovery and authority
handover resolve to the original receipt, so exactly-once firing follows from that
identity. Every schedule mutation also appends a control observation with actor context,
so the registry can be rebuilt from the lineage.
Declaring and managing schedules
Manifest-declared schedules live in tarski.toml under [schedules.<id>] and reconcile
at activation. The API can pause, resume, and trigger them, but update and removal fail
closed with schedule.manifest_origin_immutable because the manifest stays authoritative.
You manage dynamic schedules with the CLI:
tarski schedule list
tarski schedule create
tarski schedule preview
tarski schedule pause
tarski schedule trigger
tarski schedule fires
tarski schedule simulate
Each runtime mutation targets one explicit lineage and appends one reserved control observation:
| Operation | Observation/state consequence |
|---|---|
| create or replace | system.schedule.set with the complete canonical definition |
| pause or resume | system.schedule.set with the changed enabled state |
| remove | system.schedule.removed |
| trigger | an idempotent manual fire; the registry is unchanged |
| list, show, fires, preview | read-only |
The TypeScript client exposes listSchedules, readSchedule, createSchedule,
replaceSchedule, pauseSchedule, resumeSchedule, removeSchedule,
triggerSchedule, readScheduleFires, and previewSchedule. The runtime contract has no
implicit “current organization” lineage, so pass the lineage id in every generated
request. Hosted mutation requires management:schedule.write, reads require
management:schedule.read, and agent sessions are denied unless their explicit write
policy and session scope grant access.
The cron dialect is five-field with names, ranges, lists, steps, ?, L, W, #, and
@hourly-style aliases. Restricting both day fields without a ? fails closed. DST gaps
fire once at the transition instant (marked dst_adjusted); folds fire the earlier
instant. Occurrence computation is a pure function pinned by a golden conformance corpus.
Per-schedule catch-up policy covers downtime: skip, fire_once (default), or a bounded
fire_all.
Firing authority
Exactly one firing authority exists per lineage, bound to the committed
effect-authoritative activation: local live (tarski serve / tarski dev), local
offline catch-up (tarski run), or the hosted durable scheduler (which wakes hibernated
workspaces when fires come due). Replay, verification, shadow builds, and fixtures
consume recorded fire observations and never fire.
Verifying scheduled behavior
tarski schedule simulate renders the fire observations across a virtual window as
fixture JSONL. The output is byte-identical across runs, so you test scheduled behavior
the same way you test any other behavior. tarski verify includes a schedules check:
manifest definitions are validated, fixture fires must match the payload contract, and
simulation determinism is re-proven on each run.
When a fire produces no effects, tarski run reports why with stable zero-effect reasons:
schedule_fire.no_intent_derived, schedule_fire.no_effect_admitted,
effect_authority.shadow, http.credential.unresolved, or effect_request.blocked.
One-shot timer request, fire, and replay contract
Use timer.schedule for a deadline derived from evidence. Standing operational calendars
belong to the scheduler described above. Declare the timer capability and intent in
tarski.toml:
[capabilities]
timers = true
[capabilities.intents]
"intent.follow_up_timer_requested" = {
capability = "timer.schedule",
identity_keys = ["follow_up_id"]
}
The intent’s normalized object has this shape:
{
"fire_at_ms": 1784800800000,
"kind": "follow_up.due",
"reference": "follow-up:f_42",
"payload": { "follow_up_id": "f_42", "account_id": "a_7" }
}
Only fire_at_ms is required. kind defaults to timer.tick, and payload defaults to
an empty object. When ready, the effect-authoritative runtime appends one observation with
source capability:timer.schedule, the chosen kind and reference, system-owned
observed_at, and this payload:
{
"follow_up_id": "f_42",
"account_id": "a_7",
"fire_at_ms": 1784800800000,
"fired_at_ms": 1784800801250,
"late_by_ms": 1250
}
The full intent tuple is not copied automatically. Put every field the receiving mapper
needs in payload or the stable reference. fired_at_ms is the actual dispatch
instant, fire_at_ms the requested instant, and late_by_ms their non-negative
difference. Mappers can use these fields to suppress stale work without reading an
ambient clock.
Timer admission follows normal identity_keys. An unchanged re-derivation reuses its
request. Changing a non-key field changes the canonical execution contract and admits a
distinct request under that identity. The pending timer is not mutated in place.
Only the committed effect-authoritative package dispatches. Replay and shadow runs
consume recorded fire observations and never schedule them again.
Generate a fixture-ready fire deterministically:
tarski timer simulate \
--request '{"fire_at_ms":2000,"payload":{"follow_up_id":"f_42"}}'
The simulator reads no wall clock and appends nothing.