> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prodbreak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The virtual clock

> Each world has one timeline you control. Make time pass on demand; keep CI deterministic.

Every world has a single clock that starts at **t0**. Time-consuming processes (a run settling, a
transcription completing) have **named durations**, and events fire when "now" crosses their due time.

## Two modes

<CardGroup cols={2}>
  <Card title="Wall-clock ticking" icon="clock">
    "Now" advances with real time, like a staging environment — events fire on their own as time
    passes. The right default for a **long-lived raw sandbox**. *(Ships first.)*
  </Card>

  <Card title="Freeze-in-place" icon="snowflake">
    "Now" moves **only** when you advance it. Every time-derived field is reproducible by
    construction, and due timers drain *inside* your `advance()` call. The eventual default for
    **CI**. *(Roadmap.)*
  </Card>
</CardGroup>

## Advancing time

```ts theme={null}
await sandbox.clock.advance("5s");
// → { now: "2025-01-01T00:00:05Z", fired: ["task_run.completed"] }
```

When you advance time explicitly, every due event fires **in deterministic due-time order, each to
completion, before the call returns.** A `POST` finishes its own state change first, then its cascade
fires through the ordered queue. There's no "halfway" state you can accidentally observe.

## Making CI deterministic today: collapse the durations

Until freeze-in-place ships, you get deterministic **sequencing** by setting named durations to `0`.
The timer queue then drains in order on the triggering call — no waiting on real time, no flake:

```ts theme={null}
await sandbox.clock.setDurations({ run_settle: "0s", transcription: "0s" });

const run = await deck.taskRuns.create({ taskId: "task_rent" });
await sandbox.clock.advance("0s");   // drains the cascade inline
// the run is already `completed` and its webhook already fired
```

<Note>
  Durations→0 gives you deterministic **ordering** and "did the cascade fire?" assertions today.
  *Absolute* timestamps still track wall-clock until freeze lands — so if you need to assert an exact
  `created_at`, that's what freeze mode (and a pinned t0) are for. See
  [Deterministic CI](/guides/deterministic-ci).
</Note>

## Reset rewinds to t0

`reset()` empties state **and** rewinds the clock to t0. Because t0 is a fixed constant by default,
every fresh world is byte-identical. Override it per world to test date boundaries:

```ts theme={null}
await sandbox.reset({ t0: "2025-12-31T23:59:00Z" }); // test the year rollover
```