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

# Determinism & hermeticity

> How meow freezes the clock, seeds randomness, and pins the timezone so the same code produces the same output on every machine.

In `strict-web` mode (and in every `meow test` run), meow is **hermetic by
default**: the sources of ambient nondeterminism — wall-clock time, randomness,
environment variables, timezone, and locale — are routed through one governed seam
that, by default, substitutes a deterministic stand-in for the real host source. A
[grant](/concepts/permissions) swaps the real source back in.

The result: run the same code twice, on two different machines, in two different
timezones, and you get **byte-identical output**.

## The three sources

<CardGroup cols={3}>
  <Card title="Clock" icon="clock">
    A fixed virtual clock instead of wall-time.
  </Card>

  <Card title="Randomness" icon="dice">
    A seeded ChaCha20 stream instead of OS entropy.
  </Card>

  <Card title="Environment" icon="key">
    Invisible host environment instead of `process.env`.
  </Card>
</CardGroup>

### The virtual clock

By default, `Date.now()`, `new Date()`, and `performance.now()` read from a fixed
virtual origin — **`2026-06-07T00:00:00Z`** — rather than the host wall clock. The
clock advances *only* as the runtime's own timer queue fires (`setTimeout`); it
does not track real elapsed time.

```typescript theme={null}
console.log(Date.now());        // 1780790400000 — the virtual epoch, every run
const start = Date.now();
doSomeWork();
console.log(Date.now() - start); // 0 — wall-time hasn't moved
```

<Note>
  A program measuring elapsed wall-time sees zero progression under the default
  clock. That's intentional and exactly what a test runner wants — it makes
  timing-dependent code reproducible instead of flaky.
</Note>

### Seeded randomness

`Math.random()` and `crypto.getRandomValues()` draw from a **ChaCha20 CSPRNG**
seeded with a fixed 32-byte seed. The stream is identical across runs and machines.

```typescript theme={null}
console.log(Math.random()); // same value, every run, every machine
```

`crypto.subtle` (hashing, signing, key derivation) is unaffected — it's
deterministic by nature.

### Timezone & locale pinning

A fixed clock value isn't enough on its own: V8/ICU read the host `TZ` and `LANG`
to render dates and locale-default `Intl`. So under the virtual clock, meow also
pins the process timezone to **UTC** and the default locale to **en\_US.UTF-8**
before the isolate is created.

```typescript theme={null}
new Date(0).toString();           // identical across host timezones
new Intl.NumberFormat().format(1234.5);  // identical default locale

// Explicit-locale APIs are never touched:
new Intl.NumberFormat("de-DE").format(1234.5); // "1.234,5" — as you asked
```

## Granting the real host

Determinism is the default, not a cage. Opt back into real sources per-capability:

```bash theme={null}
meow run app.ts --allow-clock     # real wall-clock + timezone + locale
meow run app.ts --allow-random    # OS entropy for Math.random / crypto
meow run app.ts --allow-env       # expose host environment variables
meow run app.ts --trust           # all of the above
```

In `node-compat` mode, the real clock, OS entropy, and full environment are on by
default — no grant needed. See [Permissions & trust](/concepts/permissions) for the
full grant model.

<Tip>
  When both the clock and RNG are real (under `--trust` or in `node-compat`), meow
  skips installing the JavaScript shadows entirely and routes straight to V8's
  native intrinsics — so you pay no overhead in the hot path for determinism you
  aren't using.
</Tip>

## Why this matters

<CardGroup cols={2}>
  <Card title="Reproducible tests" icon="vial">
    No more `flaky` tests that depend on the current time, a random seed, or the CI
    box's timezone. Snapshot a value once; it holds forever.
  </Card>

  <Card title="Reproducible builds" icon="cube">
    The same inputs produce the same artifacts — across developer laptops and CI
    runners.
  </Card>

  <Card title="Edge & serverless" icon="globe">
    Code that's deterministic by default ports cleanly to distributed,
    short-lived execution environments.
  </Card>

  <Card title="Easier debugging" icon="bug">
    A bug that reproduces on your machine reproduces on everyone's. Nondeterminism
    is a grant you can see in the command line.
  </Card>
</CardGroup>

## Scope

<Warning>
  Hermeticity closes the *ambient* nondeterminism path — it's defense-in-depth,
  not a security sandbox against adversarial code.

  A program that retains a reference to an intrinsic captured before the shadows
  are installed, reaches an unshadowed intrinsic, or uses `eval`/FFI can still read
  the real host. Determinism is not isolation: don't run code you don't trust and
  assume "hermetic" means "sandboxed."
</Warning>

<Card title="Next: the permission model" icon="shield-halved" href="/concepts/permissions">
  How grants compose, and what `--trust` actually turns on.
</Card>