Module testworld 

The sealed test world.

While a ## Test runs, a thread-local TestWorld intercepts the ambient IO natives with SIMULATED resources that have real semantics: a virtual clock frozen at a fixed epoch, an in-memory filesystem seeded by Given a file …, an empty environment, and a per-test seeded RNG. There is no unrecorded entropy API to misuse — a test is a pure function of (program, seed). Capability sentences (This test may use the real filesystem.) opt individual resources back to reality under --live.

Zero cost outside tests: each native pays ONE thread-local check on an IO call (noise next to the syscall it guards); compute paths pay nothing.

Structs

Capabilities

Which resources a test may touch FOR REAL (granted by capability sentences).

TestWorld

One test’s sealed world.

Constants

SEALED_EPOCH_MS

The sealed world’s fixed epoch: 2020-01-01T00:00:00Z in ms — a stable, obviously-synthetic date (no test can accidentally depend on today).

Functions

advance_clock

Advance the virtual clock (Advance time by …). Returns false when no world is installed (the caller reports the test-only error).

install

Install a sealed world for the current thread (the runner, per test).

intercept_env_get

intercept_now

intercept_random_float

intercept_random_int

A uniform draw from min..=max off the world’s seeded stream: a word at or above the largest multiple of the span is drawn again, so no value is likelier than another — the rule every real host’s randomInt draws by.

intercept_read

intercept_sleep

A sealed sleep advances logical time INSTANTLY — the statement that turns a timeout test into a microsecond assertion. Returns true when handled.

intercept_write

restore

Put back a world a matching take returned (or None, mirroring its absence).

seed_file

Seed a fixture file (Given a file "…" containing "…".).

take

Take the installed world, if any, leaving none installed — a nested caller (a candidate page tier compared against the reference) saves whatever world its caller had before installing its own, and restores it when it is done.

uninstall

Remove the sealed world (the runner, after each test).

with_world

Run f against the installed world, if any.