Struct ShapeEngine 

pub struct ShapeEngine {
    pub runtime: Runtime,
    pub default_data: DataFrame,
    /* private fields */
}

The unified Shape execution engine

Fields

runtime: Runtime

The runtime environment

default_data: DataFrame

Default data for expressions/assignments

Implementations

impl ShapeEngine

pub fn execute( &mut self, executor: &mut impl ProgramExecutor, source: &str, ) -> Result<ExecutionResult>

Execute a Shape program from source code (sync mode)

This method allows blocking data loads (REPL mode). For scripts/backtests, use execute_async() instead.

pub async fn execute_async( &mut self, executor: &mut impl ProgramExecutor, source: &str, ) -> Result<ExecutionResult>

Execute a Shape program with async prefetching (Phase 6/8)

This method:

1. Sets Async data mode (runtime data requests use cache, not blocking)
2. Parses and analyzes the program
3. Determines required data (symbols/timeframes)
4. Prefetches data concurrently
5. Executes synchronously using cached data

Example

let provider = DataFrameAdapter::new(...);
let mut engine = ShapeEngine::with_async_provider(provider)?;
let result = engine.execute_async(&interpreter, "let sma = close.sma(20)").await?;

pub async fn execute_repl( &mut self, executor: &mut impl ProgramExecutor, source: &str, ) -> Result<ExecutionResult>

Execute a REPL command with persistent state

Unlike execute_async, this uses incremental analysis where variables and functions persist across commands. Call init_repl() once before the first call to this method.

pub fn parse_and_analyze(&mut self, source: &str) -> Result<Program>

Parse and analyze source code without executing it.

Returns the analyzed AST Program, ready for compilation. Used by the recompile-and-resume flow.

pub fn execute_repl_command( &mut self, executor: &mut impl ProgramExecutor, command: &str, ) -> Result<ExecutionResult>

Execute a REPL command

impl ShapeEngine

pub fn load_stdlib(&mut self) -> Result<()>

Load stdlib core modules only. Domain-specific modules (finance, iot, etc.) require explicit import.

impl ShapeEngine

pub fn new() -> Result<Self>

Create a new Shape engine

pub fn with_data(data: DataFrame) -> Result<Self>

Create engine with data

pub fn with_async_provider(provider: SharedAsyncProvider) -> Result<Self>

Create engine with async data provider (Phase 6)

This constructor sets up the engine with an async data provider. Call execute_async() instead of execute() to use async prefetching.

pub fn init_repl(&mut self)

Initialize REPL mode

Call this once after creating the engine and loading stdlib, but before executing any REPL commands. This configures output adapters for REPL-friendly display.

pub fn capture_bootstrap_state(&self) -> Result<EngineBootstrapState>

Capture semantic/runtime state after stdlib bootstrap.

Call this on an engine that has already loaded stdlib.

pub fn apply_bootstrap_state(&mut self, state: &EngineBootstrapState)

Apply a previously captured stdlib bootstrap state.

pub fn set_script_path(&mut self, path: impl Into<String>)

Set the script path for snapshot metadata.

pub fn script_path(&self) -> Option<&str>

Get the current script path, if set.

pub fn enable_snapshot_store(&mut self, store: SnapshotStore)

Enable snapshotting with a content-addressed store.

pub fn last_snapshot(&self) -> Option<&HashDigest>

Get last snapshot ID, if any.

pub fn snapshot_store(&self) -> Option<&SnapshotStore>

Access the snapshot store (if configured).

pub fn store_snapshot_blob<T: Serialize>(&self, value: &T) -> Result<HashDigest>

Store a serializable blob in the snapshot store and return its hash.

pub fn snapshot_with_hashes( &mut self, vm_hash: Option<HashDigest>, bytecode_hash: Option<HashDigest>, ) -> Result<HashDigest>

Create a snapshot of semantic/runtime state, with optional VM/bytecode hashes supplied by the executor.

pub fn load_snapshot( &self, snapshot_id: &HashDigest, ) -> Result<(SemanticSnapshot, ContextSnapshot, Option<HashDigest>, Option<HashDigest>)>

Load a snapshot and return its components (semantic/context + optional vm/bytecode hashes).

pub fn apply_snapshot( &mut self, semantic: SemanticSnapshot, context: ContextSnapshot, ) -> Result<()>

Apply a semantic/context snapshot to the current engine.

pub fn register_extension_modules(&mut self, modules: &[ParsedModuleSchema])

Register extension module namespaces with the runtime. Must be called before execute() so the module loader recognizes modules like duckdb.

pub fn register_language_runtime_artifacts(&mut self)

Register Shape source artifacts bundled by loaded language runtime extensions.

Each language runtime extension (e.g. Python, TypeScript) may bundle a .shape module source that defines the extension’s own namespace. The namespace is the language identifier itself (e.g. "python", "typescript") – NOT "std::core::*".

Call this after loading extensions but before execute().

pub fn set_source(&mut self, source: &str)

Set the current source text for error messages

Call this before execute() to enable source-contextualized error messages. The source is used during bytecode compilation to populate debug info.

pub fn current_source(&self) -> Option<&str>

Get the current source text (if set)

pub fn register_provider(&mut self, name: &str, provider: SharedAsyncProvider)

Register a data provider (Phase 8)

Registers a named provider for runtime data access.

Example

let adapter = Arc::new(DataFrameAdapter::new(...));
engine.register_provider("data", adapter);

pub fn set_default_provider(&mut self, name: &str) -> Result<()>

Set default data provider (Phase 8)

Sets which provider to use for runtime data access when no provider is specified.

pub fn register_type_mapping(&mut self, type_name: &str, mapping: TypeMapping)

Register a type mapping (Phase 8)

Registers a type mapping that defines the expected DataFrame structure for a given type name. Type mappings enable validation and JIT optimization.

Example

use shape_core::runtime::type_mapping::TypeMapping;

// Register the Candle type (from stdlib)
let candle_mapping = TypeMapping::new("Candle".to_string())
    .add_field("timestamp", "timestamp")
    .add_field("open", "open")
    .add_field("high", "high")
    .add_field("low", "low")
    .add_field("close", "close")
    .add_field("volume", "volume")
    .add_required("timestamp")
    .add_required("open")
    .add_required("high")
    .add_required("low")
    .add_required("close");

engine.register_type_mapping("Candle", candle_mapping);

pub fn get_runtime(&self) -> &Runtime

Get the current runtime state (for REPL)

pub fn get_runtime_mut(&mut self) -> &mut Runtime

Get mutable runtime (for REPL state updates)

pub fn get_variable_format_hint(&self, name: &str) -> Option<String>

Get the format hint for a variable (if any)

Returns the format hint specified in the variable’s type annotation. Example: let rate: Number @ Percent = 0.05 → Some(“Percent”)

pub fn format_value_string( &mut self, value: f64, type_name: &str, format_name: Option<&str>, params: &HashMap<String, Value>, ) -> Result<String>

Format a value using Shape runtime format evaluation

This uses the format definitions from stdlib (e.g., stdlib/core/formats.shape) instead of Rust fallback formatters.

Arguments

• value - The value to format (as f64 for numbers)
• type_name - The Shape type name (“Number”, “String”, etc.)
• format_name - Optional format name (e.g., “Percent”, “Currency”). Uses default if None.
• params - Format parameters as JSON (e.g., {“decimals”: 1})

Returns

Formatted string on success

Example

let formatted = engine.format_value_string(
    0.1234,
    "Number",
    Some("Percent"),
    &HashMap::new()
)?;
assert_eq!(formatted, "12.34%");

pub fn load_extension( &mut self, path: &Path, config: &Value, ) -> Result<LoadedExtension>

Load a data source extension from a shared library

Arguments

• path - Path to the extension shared library (.so, .dll, .dylib)
• config - Configuration value for the extension

Returns

Information about the loaded extension

Safety

Loading extensions executes arbitrary code. Only load from trusted sources.

Example

let info = engine.load_extension(Path::new("./libshape_ext_csv.so"), &json!({}))?;
println!("Loaded: {} v{}", info.name, info.version);

pub fn unload_extension(&mut self, name: &str) -> bool

Unload an extension by name

Arguments

• name - Extension name to unload

Returns

true if plugin was unloaded, false if not found

pub fn list_extensions(&self) -> Vec<String>

List all loaded extension names

pub fn get_extension_query_schema( &self, name: &str, ) -> Option<ParsedQuerySchema>

Get query schema for an extension (for LSP autocomplete)

Arguments

• name - Extension name

Returns

The query schema if extension exists

pub fn get_extension_output_schema( &self, name: &str, ) -> Option<ParsedOutputSchema>

Get output schema for an extension (for LSP autocomplete)

Arguments

• name - Extension name

Returns

The output schema if extension exists

pub fn get_extension(&self, name: &str) -> Option<Arc<ExtensionDataSource>>

Get an extension data source by name

pub fn get_extension_module_schema( &self, module_name: &str, ) -> Option<ParsedModuleSchema>

Get extension module schema by module namespace.

pub fn module_exports_from_extensions(&self) -> Vec<ModuleExports>

Build VM extension modules from loaded extension module capabilities.

pub fn language_runtimes(&self) -> HashMap<String, Arc<PluginLanguageRuntime>>

Return all loaded language runtimes, keyed by language identifier.

pub fn invoke_extension_module_nb( &self, module_name: &str, function: &str, args: &[ValueWord], ) -> Result<ValueWord>

Invoke one loaded module export via module namespace.

pub fn invoke_extension_module_wire( &self, module_name: &str, function: &str, args: &[WireValue], ) -> Result<WireValue>

Invoke one loaded module export via module namespace.

pub fn enable_progress_tracking(&mut self) -> Arc<ProgressRegistry>

Enable progress tracking and return the registry for subscriptions

Call this before executing code that may report progress. The returned registry can be used to subscribe to progress events.

Example

let registry = engine.enable_progress_tracking();
let mut receiver = registry.subscribe();

// In a separate task
while let Ok(event) = receiver.recv().await {
    println!("Progress: {:?}", event);
}

pub fn progress_registry(&self) -> Option<Arc<ProgressRegistry>>

Get the current progress registry if enabled

pub fn has_pending_progress(&self) -> bool

Check if there are pending progress events

pub fn poll_progress(&self) -> Option<ProgressEvent>

Poll for progress events (non-blocking)

Returns the next progress event if available, or None if queue is empty.

Trait Implementations

impl Default for ShapeEngine

fn default() -> Self

Returns the “default value” for a type.