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 communication_replay;
54pub mod compiler;
55pub mod composition;
56pub mod coroutine;
57pub mod determinism;
58pub mod driver;
59pub mod effect;
60pub mod envelope_diff;
61pub mod exec;
62pub mod exec_api;
63pub mod faults;
64pub mod guard;
65pub mod identity;
66pub mod instr;
67pub mod instruction_semantics;
68pub mod integration;
69pub mod intern;
70pub mod kernel;
71pub mod loader;
72pub mod nested;
73pub mod output_condition;
74pub mod persistence;
75pub mod runtime_contracts;
76pub mod scheduler;
77pub mod serialization;
78pub mod session;
79#[cfg(feature = "multi-thread")]
80pub mod threaded;
81pub mod trace;
82pub mod transfer_semantics;
83pub mod verification;
84pub mod vm;
85#[cfg(target_arch = "wasm32")]
86pub mod wasm;
87
88pub use architecture::{
89    EngineOwnership, EngineRole, CANONICAL_ENGINE, CROSS_TARGET_CONTRACT, ENGINE_OWNERSHIP,
90    EQUIVALENCE_SURFACES,
91};
92pub use backend::VMBackend;
93pub use bridge::{
94    EffectGuardBridge, IdentityGuardBridge, IdentityPersistenceBridge, IdentityVerificationBridge,
95    PersistenceEffectBridge,
96};
97pub use clock::SimClock;
98pub use communication_replay::{
99    CommunicationConsumeResult, CommunicationConsumption, CommunicationConsumptionArtifact,
100    CommunicationIdentity, CommunicationReplayError, CommunicationReplayMode,
101    CommunicationReplayState, CommunicationStepKind, DefaultCommunicationConsumption,
102    COMM_IDENTITY_DOMAIN_TAG, COMM_REPLAY_DUPLICATE_TAG, COMM_REPLAY_SEQUENCE_MISMATCH_TAG,
103};
104pub use composition::{
105    ComposedRuntime, CompositionCertificate, CompositionError, DeterminismCapability, MemoryBudget,
106    MemoryUsage, ProtocolBundle, SchedulerCapability, TheoremPackCapabilities,
107};
108pub use coroutine::{CoroStatus, Coroutine, CoroutineState, KnowledgeSet, Value};
109pub use determinism::{DeterminismMode, EffectDeterminismTier};
110pub use driver::NativeSingleThreadDriver;
111#[cfg(feature = "multi-thread")]
112pub use driver::NativeThreadedDriver;
113pub use effect::{
114    classify_effect_error, classify_effect_error_owned, send_fast_path_key, CorruptionType,
115    EffectError, EffectErrorCategory, EffectTraceEntry, EffectTraceTape, RecordingEffectHandler,
116    ReplayEffectHandler, SendDecisionFastPathInput, SendPayloadKind, TopologyPerturbation,
117};
118pub use envelope_diff::{
119    EffectOrderingClass, EnvelopeDiff, EnvelopeDiffArtifactV1, FailureVisibleDiffClass,
120    SchedulerPermutationClass, WaveWidthBound,
121};
122pub use exec_api::{ExecResult, ExecStatus, StepEvent, StepPack};
123pub use faults::{classify_fault, fault_code, fault_code_of, FaultClass};
124pub use guard::{GuardLayer, InMemoryGuardLayer, LayerId};
125pub use identity::{IdentityModel, ParticipantId, SiteId as IdentitySiteId, StaticIdentityModel};
126pub use instr::Instr;
127pub use integration::{run_loaded_vm_record_replay_conformance, LoadedVmReplayConformance};
128pub use intern::{StringId, SymbolTable};
129pub use kernel::VMKernel;
130pub use nested::NestedVMHandler;
131pub use output_condition::{
132    verify_output_condition, OutputConditionCheck, OutputConditionHint, OutputConditionMeta,
133    OutputConditionPolicy,
134};
135pub use persistence::{NoopPersistence, PersistenceModel};
136pub use runtime_contracts::{
137    admit_vm_runtime, determinism_profile_supported, enforce_vm_runtime_gates,
138    request_determinism_profile, requires_vm_runtime_contracts, runtime_capability_snapshot,
139    DeterminismArtifacts, RuntimeAdmissionResult, RuntimeContracts, RuntimeGateResult,
140};
141pub use scheduler::{
142    CrossLaneHandoff, LaneId as SchedulerLaneId, PriorityPolicy, SchedPolicy, SchedState,
143    Scheduler, StepUpdate,
144};
145pub use serialization::{
146    canonical_effect_trace, canonical_replay_fragment_v1, canonical_trace_v1,
147    CanonicalReplayFragmentV1, CanonicalTraceV1,
148};
149pub use session::{decode_edge_json, Edge, HandlerId, SessionId, SessionStore};
150#[cfg(feature = "multi-thread")]
151pub use threaded::{
152    ContentionMetrics, LaneHandoff, LaneId, LaneSchedulerState, LaneSelection, ThreadedVM,
153};
154pub use trace::{
155    normalize_trace, normalize_trace_v1, obs_session, strict_trace, with_tick, NormalizedTraceV1,
156    TRACE_NORMALIZATION_SCHEMA_VERSION,
157};
158pub use transfer_semantics::{decode_transfer_request, move_endpoint_bundle, TransferRequest};
159pub use verification::{
160    signValue, sign_value, verifySignedValue, verify_signed_value, AuthProof, AuthTree, Commitment,
161    DefaultVerificationModel, Hash, HashTag, Nullifier, Signature, SigningKey, VerificationModel,
162    VerifyingKey,
163};
164pub use vm::{
165    EffectTraceCaptureMode, MonitorMode, PayloadValidationMode, Program, RuntimeTuningProfile,
166    SchedExecStatus, SchedStepDebug, ThreadedRoundSemantics, VMConfig, VMState, VM,
167};
168#[cfg(target_arch = "wasm32")]
169pub use wasm::WasmVM;
telltale_vm/lib.rs

telltale_vm/
lib.rs
