simulation library

Classes

BehaviorResult
The result of one scenario behavior execution.
ContractMethod
One parsed contract method: signIn(email, password) -> User.
ContractParser
Parses declared dependency contract strings into ContractMethod pins.
DeclaredTouchpointRow
One declared dependency row consumed from the spec's External Dependencies & Contracts table (#960's output shape).
EntityFixtures
Loads committed per-entity fixture records for simulation boot.
LatencyModel
The per-world latency model: one PRNG stream seeded from the world seed, band selection by call index, jitter within the band.
LatencySample
One drawn latency: the milliseconds and the band they came from.
NetworkIsolationGuard
Installs/restores the outbound-socket interception. Idempotent and re-installable; uninstall restores the overrides that were active before install.
RetryPolicy
The retry policy: budget + exponential backoff shape.
RetrySyncEngine
The retry-with-backoff sync engine (the temporal demo feature).
SimulationBoot
Boots the app end-to-end on certified mocks.
SimulationBootReport
The result of a simulation boot.
SimulationFlavor
Compile-time flavor introspection for the simulation mode.
SimulationWhitelistConfig
Loads the isolation-guard whitelist from the project-level configuration file (.zfa.jsonsimulation.whitelist).
SocketLane
One explicitly approved network lane.
StormFailure
One fired storm's resolved failure.
SyncFailure
One recorded failure in the sync's ledger.
SyncOutcome
The sync's outcome.
VirtualClock
A deterministic virtual clock. Never touches DateTime.now().
WorldBehavior
One executable behavior in the scenario program. Drivers:
WorldCertification
The certification outcome for one world.
WorldCertifier
The world certifier: proves declared contracts by invocation.
WorldDifferentialGate
The differential gate: world binding vs real-adapter harness over the same behavior program.
WorldDifferentialResult
The differential run's result.
WorldDiffRow
One behavior's differential comparison row.
WorldLatencyBands
The latency model for one touchpoint: banded distributions (fast/slow/timeout) with deterministic band selection. Latency is VIRTUAL time — the world advances its clock, never wall time.
WorldManifest
The world manifest (schema 1).
WorldMethodProof
One method's proof outcome.
WorldPlay
One recorded invocation (the play ledger entry).
WorldRunReceipt
The world-run receipt envelope (proof.v1 + world extras).
WorldRunReceiptStore
Reads and writes world-run receipts through the ReceiptStore.
WorldRuntime
The simulated reality for one world.
WorldStorm
One failure storm: a named window of scripted failures on one touchpoint. Kinds (the issue's storm classes):
WorldTouchpoint
One touchpoint: a declared external dependency participating in the world, with its contract methods and simulation semantics.

Enums

DiffClass
One behavior's differential classification.
LatencyBand
Which band a latency sample came from.
StormFailureKind
The failure a fired storm throws/wraps, classified.
WorldBinding
The execution binding: the simulated world or the direct real-adapter harness.
WorldDiffVerdict
The gate's verdict.

Constants

kPartialWriteMarker → const String
The partial-write marker the runtime injects into a response when a partial-write storm fires: the write half-landed, honest consumers must detect and repair it.
kRealBackendMode → const bool
Whether the application was compiled with an explicit real-backend define. Used only to surface conflicts with kSimulationMode loudly (FR-012); on its own it has no simulation semantics.
kSimulationMode → const bool
Whether the application was compiled for the simulation flavor.

Functions

appendWorldCycleEvidence({required String featureDir, required String behaviorId, required String kind, required String commandLine, required String hash, required int exitCode, required String criterion, Map<String, String> extraLines = const {}}) Future<void>
Append a hash-chained world evidence entry to the feature's cycle log (<featureDir>/tdd/cycle-log.md), schema-1 chain format — the same format the run driver, doctor, and fixture commitment already parse. kind is world-cert / world-run; hash is the entry's chain hash (the world hash for certification, the run digest for runs).
contractDigestOf(String contract) String
The SHA-256 digest of a declared contract string (certification provenance: the receipt binds the exact contract text).
familyForDependency(String name) String
The simulation family for a declared dependency name: known certified families resolve by name; everything else is generic (corpus-served, contract-pinned).
loadWorldCertification(String worldsDir, String scenario) WorldCertification?
Load the committed certification receipt for scenario under worldsDir. Returns null when absent (never certified).
scaffoldWorld({required String scenario, required String feature, required List<DeclaredTouchpointRow> rows, required int seed}) WorldManifest
Scaffold a world manifest for scenario from the declared dependency rows: touchpoints (parsed contracts), the time model (seed), certified default latency bands per touchpoint, a default failure-storm schedule (the issue's storm classes for the declared touchpoint shapes), the golden corpus per method, and a default behavior program exercising every method once.
stormAt(List<WorldStorm> storms, String touchpoint, String method, int callIndex) WorldStorm?
The storm that fires for touchpoint's method on call callIndex (1-based), or null when the schedule is silent there. A storm with a null method matches every method of the touchpoint; a method-scoped storm fires only on its method (how mid-flow storms stay surgical). When several storms overlap, the LAST declared wins (later entries refine earlier ones — the manifest reads as an ordered schedule).
worldCertPath(String featureDir, String scenario) String
The certification receipt path for scenario.
worldManifestPath(String featureDir, String scenario) String
The manifest path for scenario under featureDir.
worldsDirOf(String featureDir) String
Where a feature's worlds live.

Exceptions / Errors

NetworkIsolationViolation
Thrown when code running under NetworkIsolationGuard attempts to open a real socket. Extends Error (not Exception) so catch (e) blocks that are not explicitly isolating network access do not silently swallow the certification failure.
SimulationFixtureError
Raised at simulation boot when an entity's committed fixtures are missing or corrupt. The message always names the affected entity and the fixture file path (FR-009).
SimulationFlagConflict
The build-time configuration conflict for the simulation flavor.
WorldManifestError
Raised when a world manifest is structurally invalid. The message carries the machine-actionable --> fix: line (errors-are-an-API).
WorldProgramError
Raised when the manifest's behavior program references an unknown touchpoint or method — the world refuses to run a program that does not match its declared contracts (never a silent no-op).