Replay and time
Worlds makes tests replayable: the same seed, configuration and ordered request sequence produce byte-identical world state. This applies to the shared world engine. It does not make an agent's model output or external services deterministic.
The guarantee
For the same runtime version and inputs, a replay produces the same canonical dump, recorded event history and diff before-images. The dump contains the world's resource objects, counters, marks and logical clock, together with the histories and delivery records supported by that world.
The guarantee holds across processes, machines and reruns. A dump compares recorded state; a mark and diff shows what a test changed. Diffs exclude internal events, which have their own query endpoint.
Replay a test
- Create a fresh world from the same seed and use the same configuration.
- Apply the same failure conditions, if any.
- Send requests in the same order, including clock advances and marks.
- Finish any supported asynchronous delivery used by the test, then compare dumps or assertions.
Keep the runtime version and seed bytes with the test. Await requests when their order matters: a world serializes writes, but the arrival order of concurrent requests is an input to the replay.
| Inspect | Admin endpoint |
|---|---|
| Canonical recorded dump (private history omitted) | GET /admin/worlds/:id/dump |
| Changes since a mark | GET /admin/worlds/:id/diff?from=<mark> |
| Event history | GET /admin/worlds/:id/events |
The dashboard workflow guide covers saved-input reruns and inspecting test evidence.
Reset and restart
worlds world reset <world_id> restores the seed, clock and counters. It clears mutations, history, marks, active scenarios and any request replay caches. Request numbering and API-key use counts restart too. Existing keys, admin tokens and configured webhook endpoints survive.
Reset waits up to five seconds for in-flight requests. Requests arriving during reset wait for the new world. An older request that outlives that wait receives a reset-related 500 when it resumes; it is neither executed nor logged in the reset world. An old webhook send cannot write its result into the reset world.
Restarting the server preserves persisted world state. Reset clears replay history; exporting a seed carries settled starting state without request caches.
How
| Mechanism | Replay behavior |
|---|---|
| Persisted IDs and counters | Object IDs derive from seed data and world counters. Their representation follows the world's API. |
| Logical time | Timestamps come from the seed's epoch and explicit clock advances or automatic ticks. |
| Transactional handlers | Resource changes and their events commit or roll back together. |
| One writer per world | Each world has its own database, lock and counters. |
| Scenario counters | Matching failures occur at the same requests on each replay. |
| Before-images | Updates and deletes retain prior object state for diffs. |
Separate worlds can interleave on one server process. Synchronous database work still shares one JavaScript thread.
Logical clock
The clock uses integer Unix seconds. In manual mode, only an admin advance moves it. In automatic mode, a fixed tick runs after route and preflight checks, before replay-cache lookup and handler execution.
Authentication failures, injected responses, unknown routes and preflight parameter refusals do not tick. A handler's own validation failure does tick. A supported replay-cache hit also ticks. These distinctions are part of the request contract.
Clock advancement and due work share one transaction. If due work fails, both roll back. If the tick succeeds and the subsequent handler refuses a request, the tick remains committed.
Scheduled lifecycle work is world-specific. An advance runs only the capabilities that the selected world implements and the seed enables. Consult that world's reference for its schedule, limits and starting records.
Request replay caches
If your world supports request replay, its reference defines eligible methods and paths, key matching, stored responses and expiry. Reusing a key does not imply that every request is deduplicated.
Supported caches survive restart with their original expiry. Reset clears them, and seed export carries settled state without retry history. See storage and upgrades before reusing retained worlds with a different runtime.
Boundaries (deliberate)
Inputs and credentials
World IDs, API keys and admin tokens are random harness credentials, excluded from dumps. They do not become connector object IDs.
Request values remain your inputs. A wall-clock timestamp, random value, different request order or changing external response can produce a different result. The guarantee compares equivalent inputs on the same runtime version.
Webhook delivery
If your world supports webhook delivery, eligible deliveries run in event-creation order unless a scenario changes it. Outcomes depend on your listener's responses. Supported retry backoff uses logical time: 60s × 2^(attempt−1).
Automatic delivery runs outside the world lock. For repeatable delivery assertions on supported worlds, set auto_deliver: false and call POST /admin/worlds/:id/webhooks/flush at fixed points. Alternatively, stop sending requests and flush until a batch is empty before marking or comparing state. Retries scheduled for a future logical time remain pending until the clock advances.
Delivery is at least once across a server restart. If the process stops during a send, that pending delivery can be sent again. Deduplicate listener effects by event ID.
Transport timing
Injected latency and webhook HTTP round trips use wall-clock time. They affect arrival timing, not the logical timestamps stored in objects.
Where delivery authentication is supported, header timestamps can use delivery time for SDK verification. These timestamps are excluded from world state. If the world supports signature_time: "logical", use it when comparing headers across replays and configure verifier tolerance for the fixture's age. Recorded event timestamps use logical time.