# MoonLab

MoonLab defines the domain language for reproducibly exercising distributed-system models under controlled time, scheduling, communication, and failure conditions.

## Language

**Deterministic Simulation**:
A controlled execution in which the same scenario, seed, configuration, and compatible engine version produce the same observable decisions and trace.
_Avoid_: Chaos test, real-time test, ordinary randomized test

**System Model**:
A MoonBit representation of distributed behavior written against MoonLab's controlled simulation boundary so that its nondeterministic inputs remain reproducible.
_Avoid_: Production process, external service, deployed cluster

**Node**:
An identified participant in a System Model that owns local state and reacts to delivered Events.
_Avoid_: Host, process, machine

**Crash**:
A fault transition that places a Node Down and discards its volatile state and pending local work without deleting committed Stable Storage.
_Avoid_: Network Partition, pause, graceful shutdown

**Restart**:
A fault transition that boots a Down Node with fresh volatile state while retaining its committed Stable Storage.
_Avoid_: Resume, retry, state restoration

**Message**:
A System Model payload sent between Nodes through MoonLab's simulated network.
_Avoid_: Event, Effect, network packet

**Envelope**:
A uniquely identified simulated transmission that carries one Message from a source Node to a destination Node and may have one or more delivery attempts.
_Avoid_: Message, Event, connection

**Event**:
An input selected and delivered by a Simulation Run to drive one Node state transition.
_Avoid_: Effect, callback, log entry

**Effect**:
A declarative request emitted by a Node transition for the simulation engine to interpret after the transition completes.
_Avoid_: Event, direct side effect, callback

**Scenario**:
A complete declared setup for one family of Simulation Runs, including the System Model inputs and the conditions under which execution is evaluated.
_Avoid_: Test case, script, deployment

**Runner**:
A model-specific executable that statically registers typed Scenarios and exposes MoonLab's shared run, replay, shrink, and inspection commands.
_Avoid_: Simulation engine, dynamic plugin host, generic interpreter

**Decision Stream**:
The ordered record of engine choices among enabled actions, sufficient to reproduce the scheduling path of a compatible Simulation Run.
_Avoid_: Random-number stream, Event log, Trace

**Replay Artifact**:
A versioned machine-readable record that binds a Decision Stream and run inputs to a compatible engine and Scenario for exact reproduction.
_Avoid_: Trace, Run Report, random seed

**Replay Compatibility**:
The declared contract under which an engine, System Model, Scenario, inputs, and Replay Artifact may reproduce the same recorded decisions.
_Avoid_: Semantic version, best-effort parsing, Replay divergence

**Trace**:
An ordered explanatory record of selected actions and their observable consequences during a Simulation Run.
_Avoid_: Decision Stream, Replay Artifact, console log

**Run Report**:
A versioned machine-readable summary of a completed Simulation Run, including its Run Outcome, Findings, statistics, and artifact identities.
_Avoid_: Trace, Replay Artifact, terminal output

**Virtual Time**:
The simulation-owned logical time used to order delayed communication, timers, storage completion, and scheduled failures without consulting wall-clock time.
_Avoid_: Wall-clock time, CPU time, test duration

**Enabled Action**:
An engine action eligible for selection in the current simulation state, ordered by a stable key before exploration chooses among alternatives.
_Avoid_: Effect, Event, scheduled callback

**Timer**:
A volatile delayed Event identified by a Node-local Timer ID, replaced by setting the same ID again and removed idempotently by cancellation.
_Avoid_: Virtual Time, durable schedule, wall-clock timer

**Network Partition**:
A simulated communication boundary that prevents selected Nodes or groups from exchanging Messages until the boundary is healed.
_Avoid_: Node crash, message delay, process outage

**Fault Plan**:
A Scenario declaration of specific faults to make eligible at specified Virtual Times or model milestones.
_Avoid_: Fault Policy, test script, production incident

**Fault Policy**:
A bounded rule that introduces eligible fault alternatives during schedule exploration without prescribing the exact choices of one Simulation Run.
_Avoid_: Fault Plan, retry policy, probability log

In v0.1 a Fault Policy is a named finite set of scheduled fault alternatives. Selecting one alternative removes its siblings and records the selected index in the Decision Stream.

**Stable Storage**:
Node-associated simulated durable state that survives Node crashes and restarts under the declared storage semantics.
_Avoid_: Host filesystem, database, in-memory Node state

**Storage Request**:
An asynchronous Node Effect that reads Stable Storage or atomically applies a batch of key writes and deletions before producing a completion Event.
_Avoid_: Direct map mutation, filesystem operation, Node state update

**Choice Point**:
A Node request for the engine to select one item from a finite non-empty set of model-defined alternatives and record the selected index in the Decision Stream.
_Avoid_: Scheduler race, unrecorded randomness, Fault Policy

**Safety Invariant**:
A property over observable simulation state that must remain true after every selected engine action.
_Avoid_: Assertion log, final expectation, liveness proof

**Observation**:
A System Model's immutable domain projection of a simulation Snapshot, used by correctness conditions without exposing mutable engine internals.
_Avoid_: Snapshot, Trace event, debug dump

**Bounded Eventually Condition**:
A property required to become true within a declared finite action or Virtual Time horizon.
_Avoid_: Safety Invariant, unbounded liveness proof, fairness guarantee

**Run Outcome**:
A structured classification of why a Simulation Run ended, distinguishing verified completion, violations, quiescence, resource limits, replay divergence, and model errors.
_Avoid_: Exit code, log message, boolean result

**Resource Budget**:
A Scenario's finite allowance for actions, Virtual Time, pending work, artifacts, storage, and shrinking within MoonLab's hard safety limits.
_Avoid_: Wall-clock timeout, benchmark target, operating-system limit

**Failure Signature**:
The stable identity of a particular failure class within a Scenario, used to decide whether a shrunk run preserves the original failure.
_Avoid_: Error message, stack trace, Run Outcome

**Shrinker**:
A budgeted search that removes or simplifies recorded decisions while retaining the same Failure Signature and valid replay.
_Avoid_: Model checker, debugger, global minimizer

**Quiescence**:
A simulation state with no Enabled Action and no future scheduled work, whose success or failure depends on the Scenario's declared termination conditions.
_Avoid_: Passed, deadlock, timeout