telltale_vm/
lib.rs

1//! Bytecode VM for choreographic session type protocols.
2//!
3//! This crate provides a standalone, embeddable virtual machine that executes
4//! choreographic protocols projected to local session types. The VM validates
5//! every instruction against its session type monitor, ensuring protocol
6//! conformance at runtime.
7//!
8//! # Architecture
9//!
10//! The VM follows the Lean specification in `lean/Runtime/VM/`:
11//! - **Instructions** ([`instr::Instr`]): bytecode ops for send/recv/choice/session lifecycle
12//! - **Coroutines** ([`coroutine::Coroutine`]): lightweight execution units, one per role
13//! - **Sessions** ([`session::SessionStore`]): manage session lifecycle and namespaces
14//! - **Buffers** ([`buffer::BoundedBuffer`]): bounded message channels with backpressure
15//! - **Scheduler** ([`scheduler::Scheduler`]): policy-based coroutine scheduling
16//! - **Loader** ([`loader`]): dynamic choreography loading with validation
17//! - **Compiler** ([`compiler`]): compile `LocalTypeR` to bytecode
18//!
19//! The VM is the **single execution engine** for simulation and runtime
20//! orchestration. Higher-level systems (e.g. `telltale-simulator`) wrap the
21//! VM with deterministic middleware for network latency, faults, property
22//! monitoring, and checkpointing.
23//!
24//! **Nested simulation** is supported via [`nested::NestedVMHandler`], which
25//! allows a VM coroutine to host an inner VM for distributed or hierarchical
26//! simulations.
27//!
28//! # Effect Handler Contract
29//!
30//! The VM's [`effect::EffectHandler`] is synchronous, deterministic, and
31//! **session-local**. It must not depend on global time or shared mutable
32//! state across sessions. This is distinct from the async, typed
33//! `telltale_choreography::ChoreoHandler` used by generated choreography code.
34//!
35//! # Usage
36//!
37//! ```ignore
38//! use telltale_vm::{VM, VMConfig, compiler, loader::CodeImage};
39//!
40//! let config = VMConfig::default();
41//! let mut vm = VM::new(config);
42//! let image = CodeImage::from_local_types(&local_types, &global_type);
43//! let sid = vm.load_choreography(image, &handler)?;
44//! while vm.step(&handler)? {}
45//! ```
46
47pub mod architecture;
48pub mod backend;
49pub mod bridge;
50pub mod buffer;
51pub mod clock;
52pub mod commit_common;
53pub mod compiler;
54pub mod composition;
55pub mod coroutine;
56pub mod determinism;
57pub mod driver;
58pub mod effect;
59pub mod envelope_diff;
60pub mod exec;
61pub mod exec_api;
62pub mod faults;
63pub mod guard;
64pub mod identity;
65pub mod instr;
66pub mod instruction_semantics;
67pub mod integration;
68pub mod intern;
69pub mod kernel;
70pub mod loader;
71pub mod nested;
72pub mod output_condition;
73pub mod persistence;
74pub mod runtime_contracts;
75pub mod scheduler;
76pub mod serialization;
77pub mod session;
78#[cfg(feature = "multi-thread")]
79pub mod threaded;
80pub mod trace;
81pub mod transfer_semantics;
82pub mod verification;
83pub mod vm;
84#[cfg(target_arch = "wasm32")]
85pub mod wasm;
86
87pub use architecture::{
88    EngineOwnership, EngineRole, CANONICAL_ENGINE, CROSS_TARGET_CONTRACT, ENGINE_OWNERSHIP,
89    EQUIVALENCE_SURFACES,
90};
91pub use backend::VMBackend;
92pub use bridge::{
93    EffectGuardBridge, IdentityGuardBridge, IdentityPersistenceBridge, IdentityVerificationBridge,
94    PersistenceEffectBridge,
95};
96pub use clock::SimClock;
97pub use composition::{
98    ComposedRuntime, CompositionCertificate, CompositionError, DeterminismCapability, MemoryBudget,
99    MemoryUsage, ProtocolBundle, SchedulerCapability, TheoremPackCapabilities,
100};
101pub use coroutine::{CoroStatus, Coroutine, CoroutineState, KnowledgeSet, Value};
102pub use determinism::{DeterminismMode, EffectDeterminismTier};
103pub use driver::NativeSingleThreadDriver;
104#[cfg(feature = "multi-thread")]
105pub use driver::NativeThreadedDriver;
106pub use effect::{
107    classify_effect_error, classify_effect_error_owned, send_fast_path_key, CorruptionType,
108    EffectError, EffectErrorCategory, EffectTraceEntry, EffectTraceTape, RecordingEffectHandler,
109    ReplayEffectHandler, SendDecisionFastPathInput, SendPayloadKind, TopologyPerturbation,
110};
111pub use envelope_diff::{
112    EffectOrderingClass, EnvelopeDiff, EnvelopeDiffArtifactV1, FailureVisibleDiffClass,
113    SchedulerPermutationClass, WaveWidthBound,
114};
115pub use exec_api::{ExecResult, ExecStatus, StepEvent, StepPack};
116pub use faults::{classify_fault, fault_code, fault_code_of, FaultClass};
117pub use guard::{GuardLayer, InMemoryGuardLayer, LayerId};
118pub use identity::{IdentityModel, ParticipantId, SiteId as IdentitySiteId, StaticIdentityModel};
119pub use instr::Instr;
120pub use integration::{run_loaded_vm_record_replay_conformance, LoadedVmReplayConformance};
121pub use intern::{StringId, SymbolTable};
122pub use kernel::VMKernel;
123pub use nested::NestedVMHandler;
124pub use output_condition::{
125    verify_output_condition, OutputConditionCheck, OutputConditionHint, OutputConditionMeta,
126    OutputConditionPolicy,
127};
128pub use persistence::{NoopPersistence, PersistenceModel};
129pub use runtime_contracts::{
130    admit_vm_runtime, determinism_profile_supported, enforce_vm_runtime_gates,
131    request_determinism_profile, requires_vm_runtime_contracts, runtime_capability_snapshot,
132    DeterminismArtifacts, RuntimeAdmissionResult, RuntimeContracts, RuntimeGateResult,
133};
134pub use scheduler::{
135    CrossLaneHandoff, LaneId as SchedulerLaneId, PriorityPolicy, SchedPolicy, SchedState,
136    Scheduler, StepUpdate,
137};
138pub use serialization::{
139    canonical_effect_trace, canonical_replay_fragment_v1, canonical_trace_v1,
140    CanonicalReplayFragmentV1, CanonicalTraceV1,
141};
142pub use session::{decode_edge_json, Edge, HandlerId, SessionId, SessionStore};
143#[cfg(feature = "multi-thread")]
144pub use threaded::{
145    ContentionMetrics, LaneHandoff, LaneId, LaneSchedulerState, LaneSelection, ThreadedVM,
146};
147pub use trace::{
148    normalize_trace, normalize_trace_v1, obs_session, strict_trace, with_tick, NormalizedTraceV1,
149    TRACE_NORMALIZATION_SCHEMA_VERSION,
150};
151pub use transfer_semantics::{decode_transfer_request, move_endpoint_bundle, TransferRequest};
152pub use verification::{
153    signValue, sign_value, verifySignedValue, verify_signed_value, AuthProof, AuthTree, Commitment,
154    DefaultVerificationModel, Hash, HashTag, Nullifier, Signature, SigningKey, VerificationModel,
155    VerifyingKey,
156};
157pub use vm::{
158    EffectTraceCaptureMode, MonitorMode, PayloadValidationMode, Program, RuntimeTuningProfile,
159    SchedExecStatus, SchedStepDebug, ThreadedRoundSemantics, VMConfig, VMState, VM,
160};
161#[cfg(target_arch = "wasm32")]
162pub use wasm::WasmVM;
telltale_vm/lib.rs

telltale_vm/
lib.rs
