zapcode_core/lib.rs
1//! # zapcode-core
2//!
3//! A minimal, secure TypeScript interpreter for AI agent code execution.
4//!
5//! ## Architecture
6//!
7//! ```text
8//! TypeScript source
9//! │
10//! ▼
11//! ┌─────────┐
12//! │ parser │ oxc_parser → ZapcodeIR (parser/ir.rs)
13//! └────┬────┘
14//! ▼
15//! ┌──────────┐
16//! │ compiler │ ZapcodeIR → stack-based bytecode (compiler/instruction.rs)
17//! └────┬─────┘
18//! ▼
19//! ┌─────────┐
20//! │ vm │ Execute bytecode, snapshot at external calls, resume later
21//! └────┬────┘
22//! ▼
23//! VmState::Complete(value) | VmState::Suspended { snapshot }
24//! ```
25//!
26//! ## Key modules
27//!
28//! - [`parser`] — Walks the oxc AST and emits [`parser::ir::ZapcodeIR`]
29//! - [`compiler`] — Lowers IR to [`compiler::instruction::Instruction`] bytecode
30//! - [`vm`] — Stack-based VM that executes bytecode; entry point is [`ZapcodeRun`]
31//! - [`value`] — Runtime value types ([`Value`], closures, generators)
32//! - [`snapshot`] — Serialize/deserialize VM state for suspension and resumption
33//! - [`sandbox`] — Resource limits (memory, time, stack depth, allocations)
34//! - [`error`] — Error types used across all modules
35//!
36//! ## Security model
37//!
38//! The sandbox is enforced at the language level: no filesystem, network, env,
39//! `eval`, `import`, or `require`. The only way guest code can interact with the
40//! host is through registered external functions that suspend the VM.
41
42pub mod compiler;
43pub mod error;
44pub mod parser;
45pub mod sandbox;
46pub mod snapshot;
47pub mod value;
48pub mod vm;
49
50pub use error::ZapcodeError;
51pub use sandbox::ResourceLimits;
52pub use snapshot::ZapcodeSnapshot;
53pub use value::Value;
54pub use vm::{RunResult, VmState, ZapcodeRun};