# TimeWarp v0.1.0 - Table of Contents

> Optimistic parallel discrete-event simulation (Time Warp) on the BEAM: logical processes execute events speculatively and roll back automatically on causality violations, so models implement only pure event handling and never write rollback logic.

## Pages

- [TimeWarp](readme.md)
- [Contributing](contributing.md)
- [License](license.md)

## Modules

- [TimeWarp](TimeWarp.md): Optimistic parallel discrete-event simulation on the BEAM (spec §7).
- [TimeWarp.Coordinator](TimeWarp.Coordinator.md): GVT computation, fossil-collect trigger, run control and termination (spec §3.1, §6).
- [TimeWarp.Event](TimeWarp.Event.md): Unit of both scheduling and inter-LP messaging (spec §4.1).
- [TimeWarp.Examples.BufferedWindow](TimeWarp.Examples.BufferedWindow.md): Keyed tumbling windows, watermark-and-buffer style — the conservative-shaped OPPONENT
to `Examples.KeyedWindow`, for the eager-vs-buffered stream experiment (Phase 5).
- [TimeWarp.Examples.DecayingPHOLD](TimeWarp.Examples.DecayingPHOLD.md): A draining variant of PHOLD (spec §14.1). Each processed event schedules one
follow-up to a random LP at `at + delay` — but only if that time is still below
the horizon. Tokens therefore fall off the end of the horizon over time and the
population drains to zero, driving the system to genuine quiescence.
- [TimeWarp.Examples.KeyedWindow](TimeWarp.Examples.KeyedWindow.md): Keyed tumbling-window aggregation — the Phase 5 output-commit *instrument* (§6.4).
- [TimeWarp.Examples.NeighbourPHOLD](TimeWarp.Examples.NeighbourPHOLD.md): PHOLD with **locality** — the workload §12's placement lever needs.
- [TimeWarp.Examples.PHOLD](TimeWarp.Examples.PHOLD.md): PHOLD — the standard PDES stress benchmark (spec §14.1).
- [TimeWarp.Examples.Spin](TimeWarp.Examples.Spin.md): A synthetic per-fold compute cost for the eager-vs-buffered stream experiment.
- [TimeWarp.LP](TimeWarp.LP.md): A logical process (spec §3, §4.2, §5). One GenServer per LP. Executes events
speculatively in `{timestamp, seq}` order, rolls back on stragglers and
processed-twin anti-messages, and un-sends downstream effects via anti-messages.
- [TimeWarp.Model](TimeWarp.Model.md): What a domain model implements (spec §7). The engine handles all Time Warp
mechanics — rollback, anti-messages, GVT, fossil collection.
- [TimeWarp.Rand](TimeWarp.Rand.md): Sanctioned, purely-functional seeded PRNG (Mitigation 3a, spec §8).
- [TimeWarp.Telemetry](TimeWarp.Telemetry.md): Telemetry-from-birth (Mitigation 2, spec §10). Every rollback, anti-message,
and GVT cycle emits an event from Phase 0 — because rollback-rate is the
diagnostic you need while debugging *the engine itself*, not a Phase 1 luxury.

- Exceptions
  - [TimeWarp.CommitmentFloorViolation](TimeWarp.CommitmentFloorViolation.md): Raised by the **Commitment-Floor Guard** (Mitigation 1, spec §6/§16).
  - [TimeWarp.DivergenceError](TimeWarp.DivergenceError.md): Raised by the **Divergence Detector** (Mitigation 3b, spec §7/§16) under
`check_purity: true`.
  - [TimeWarp.ThrashHalt](TimeWarp.ThrashHalt.md): Raised/reported when the **thrash circuit breaker** (Mitigation 2, spec §11.1)
trips: sustained rollback rate above threshold means optimism is losing to
churn. Fail fast rather than burn hours; the decomposition or workload is
wrong for Time Warp.

