v0.2.0 — commit/2 returns pruned state

Added

• c:TimeWarp.Model.commit/2 may return {:ok, new_model_state} in addition to
  :ok. Fossil collection threads the returned state back into the logical
  process, which gives a model the only point at which it can release state that a
  commit has made unreachable. handle_event/3 never observes GVT and so cannot
  determine what is safe to drop; a model that accumulates per-event state and
  always returns :ok grows for the length of the run. Events are committed in
  ascending virtual-time order and the state is threaded through that fold, so
  commit order is now observable in the resulting state.

  Pruning is bounded by GVT lag rather than immediate: a rollback restores a state
  snapshot from history, and snapshots at or above GVT were taken before the prune,
  so they still reference the released terms until the same fossil-collection pass
  drops them.

  Returning :ok remains valid, so existing models are unaffected.

• :lp_call_timeout — timeout in milliseconds for the coordinator's own calls
  into logical processes, default 5_000. These execute inside the coordinator
  process and a logical process may be remote, so exceeding the timeout fails the
  run rather than an individual call.

• :quiescence_timeout_ms — ceiling on the freeze-confirm quiescence poll,
  default 1_000. The workable value scales with link latency, so a distributed
  run may require more than a local one.

• TimeWarp.stop_run/1 cancels a run, tearing down its logical processes and
  returning the engine to idle. The function existed on the coordinator and the
  public documentation directed callers into that internal module; it is now part
  of the public surface.

  It waits without a timeout. Teardown reaches into every placement node's
  supervisor, which can exceed the default five-second call timeout on a
  multi-node run; a caller that timed out would exit while the teardown continued
  and completed, reporting a crash from a call that had in fact worked.

Changed

• TimeWarp.start_run/1 returns {:error, :run_active} when a run is already in
  progress, leaving the active run untouched.

• TimeWarp.Examples.KeyedWindow and TimeWarp.Examples.BufferedWindow release
  each window's accumulator and buffer on commit. Both previously retained every
  window for the length of the run.

Fixed

• start_run/1 against an active run matched no clause and raised
  FunctionClauseError inside the coordinator. This terminated the coordinator and
  every caller awaiting the active run, so the run already in progress was lost
  and the failure surfaced as a crash in the second.

• Three coordinator calls into logical processes — the per-process dump behind
  report/1, the GVT query, and the freeze-confirm poll — used the default
  five-second call timeout while executing inside the coordinator process. A remote
  or slow logical process therefore terminated the coordinator instead of failing a
  single call. These now honour :lp_call_timeout.

• The test suite aborted before ExUnit started when distribution was unavailable,
  reporting zero tests run. Tests requiring distribution are tagged :distributed
  and excluded when Node.start/2 fails.

Documentation

• :placement, :gvt_mode and :net_delay are documented in the TimeWarp
  moduledoc. All three were read by the coordinator and absent from the option
  list. :net_delay is marked test-only.

• The one-run-per-BEAM constraint is stated explicitly. The coordinator is a
  global singleton, and start_run/1 tears down every logical process on the
  placement nodes without scoping the teardown to a single run, so concurrent runs
  destroy one another.

• :time_window documents that it is the only bound on retained state. Fossil
  collection reclaims only below GVT, so a workload holding GVT near the floor
  grows retained state until the VM exhausts memory, and :none places no limit
  on how far a logical process runs ahead.

• The TimeWarp moduledoc example referenced a model that does not exist and
  would not compile, and set time_window: :none — the value documented
  immediately below it as unbounded. It now uses TimeWarp.Examples.PHOLD with a
  binding window.

• TimeWarp.Coordinator's moduledoc described the superseded stop-the-world
  computation as current and Mattern's algorithm as future work, though
  :gvt_mode defaults to :mattern. It now leads with Mattern's algorithm as the
  computation in use, and presents the stop-the-world variant as the test oracle
  and termination confirmation it actually is.

• References to an unpublished specification (§N, Mitigation N, Phase-N)
  are resolved to their meaning throughout the published modules.

---

Full changelog: https://github.com/thatsme/timewarp/blob/v0.2.0/CHANGELOG.md
Documentation: https://hexdocs.pm/timewarp/0.2.0
Package: https://hex.pm/packages/timewarp/0.2.0

v0.1.0 — Initial release

Optimistic parallel discrete-event simulation (Time Warp) on the BEAM. Logical processes execute events speculatively and roll back automatically when causality is violated; the engine propagates corrections through the causal message graph, so a model implements only pure event handling and never writes rollback logic.

Included

• Time Warp core — speculative execution, anti-messages, annihilation, automatic rollback.
• Distributed Global Virtual Time (Mattern), fossil collection, and the output-commit quarantine.
• Safety and tuning — deadlock-free time window, opt-in lazy cancellation, thrash circuit breaker, and a double-call purity probe.
• Distribution — single-node and two-node, location-transparent.
• Example models — PHOLD, DecayingPHOLD, and KeyedWindow / BufferedWindow.

Correctness

Validated against a sequential-equivalence oracle: every optimistic run produces byte-identical committed results to an in-timestamp-order execution of the same model, including under adversarial out-of-order arrival and across two nodes. An exhaustive small-scale model check exercises the GVT algorithm.

Status

Research- and engineering-quality, not production software. The container-terminal reference application that motivated the design is validated for engine correctness only and has never been calibrated against real operational data.

Implements Jefferson's Time Warp (TOPLAS, 1985) with Mattern's distributed GVT (JPDC, 1993). Licensed under Apache-2.0.