stone-lang 0.1.0

package/StoneEngineService.js

@@ -0,0 +1,1727 @@
+/**
+ * Stone Engine Service
+ *
+ * Central service for Stone language parsing, graph building, and execution.
+ * Provides a unified API for all Stone engine operations with caching and storage.
+ */
+
+import { Lexer } from './frontend/parsing/tokenizer.js';
+import { Parser } from './frontend/parsing/astBuilder.js';
+import { TypeChecker } from './frontend/type-checker/typeChecker.js';
+import { ModuleResolver } from './frontend/utils/moduleResolver.js';
+import { buildFilePath } from '../utils/filePathResolver.js';
+import { Compiler } from './backends/js-vm/compiler.js';
+import { CompiledFunction } from './backends/js-vm/bytecode.js';
+import { VM } from './backends/js-vm/vm/index.js';
+import { BufferedOutputAdapter } from './adapters/OutputAdapter.js';
+import { createTerminalConstructors } from './frontend/parsing/terminal-registry.js';
+import { setFileSystemAdapter } from './backends/js-vm/primitives/file.js';
+import { registerOverload, clearDynamicOverloads } from './backends/js-vm/primitives/overloads.js';
+
+/**
+ * Stone Engine Service
+ *
+ * Central service class for Stone language parsing, type checking, compilation,
+ * and execution. Provides a unified API for all Stone engine operations with
+ * built-in caching and storage capabilities.
+ *
+ * @example
+ * // Basic usage
+ * const service = new StoneEngineService();
+ * const result = service.compileAndExecute('let x = 2 + 3; print(x)');
+ *
+ * @example
+ * // With modules
+ * service.setFilesSource(filesMap);
+ * const result = await service.executeWithModules(source, { currentPath: '/scripts/main.stn' });
+ */
+class StoneEngineService {
+  /**
+   * Create a new StoneEngineService instance
+   */
+  constructor() {
+    /**
+     * Map of currently running scripts (fileId -> execution state)
+     * @type {Map<string, {status: string, startTime: number, fileId: string, source: string}>}
+     */
+    this.runningScripts = new Map();
+
+    /**
+     * Map of execution results with metadata (fileId -> result)
+     * @type {Map<string, Object>}
+     */
+    this.executionResults = new Map();
+
+    /**
+     * AST cache (sourceHash -> AST)
+     * @type {Map<string, Object>}
+     */
+    this.astCache = new Map();
+
+    /**
+     * Execution graph cache (sourceHash+nodeInsertsHash -> graph)
+     * @type {Map<string, Object>}
+     */
+    this.graphCache = new Map();
+
+    /**
+     * Maximum number of entries in caches
+     * @type {number}
+     */
+    this.maxCacheSize = 100;
+
+    /**
+     * Execution history per file (fileId -> array of executions)
+     * @type {Map<string, Array>}
+     */
+    this.executionHistory = new Map();
+
+    /**
+     * Maximum number of history entries per file
+     * @type {number}
+     */
+    this.maxHistoryPerFile = 10;
+
+    /**
+     * Module resolver for handling imports and module loading
+     * @type {ModuleResolver}
+     */
+    this.moduleResolver = new ModuleResolver();
+
+    /**
+     * File system state (set by consumer)
+     * @type {Map|Array|null}
+     */
+    this.filesSource = null;
+
+    /**
+     * Function to load file content by ID (set by consumer)
+     * @type {Function|null}
+     */
+    this.fileLoader = null;
+
+    /**
+     * File system adapter for file module (set by consumer)
+     * Must have readFile(path) and writeFile(path, content) methods
+     * @type {Object|null}
+     */
+    this.fileSystemAdapter = null;
+
+    /**
+     * Cached builtins.stn exports (auto-imported into every script)
+     * @type {Object|null}
+     */
+    this.stnBuiltinsExports = null;
+
+    /**
+     * Bytecode compiler instance
+     * @type {Compiler}
+     */
+    this.compiler = new Compiler();
+
+    /**
+     * Bytecode VM instance
+     * @type {VM}
+     */
+    this.vm = new VM();
+
+    /**
+     * Bytecode cache (sourceHash -> compiled bytecode)
+     * @type {Map<string, Object>}
+     */
+    this.bytecodeCache = new Map();
+  }
+
+  /**
+   * Tag a CompiledFunction and all nested functions with moduleIdx
+   * @param {CompiledFunction} fn - Function to tag
+   * @param {number} moduleIdx - Module index to assign
+   * @param {Set} visited - Already visited functions (to avoid cycles)
+   */
+  _tagFunctionWithModuleIdx(fn, moduleIdx, visited = new Set()) {
+    if (!fn || !(fn instanceof CompiledFunction) || visited.has(fn)) {
+      return;
+    }
+    visited.add(fn);
+    fn.moduleIdx = moduleIdx;
+
+    // Recursively tag any nested functions in constants
+    if (fn.constants) {
+      for (const constant of fn.constants) {
+        if (constant instanceof CompiledFunction) {
+          this._tagFunctionWithModuleIdx(constant, moduleIdx, visited);
+        }
+      }
+    }
+  }
+
+  /**
+   * Load builtins.stn exports (auto-imported primitives)
+   * Cached after first load
+   */
+  async loadStnBuiltins() {
+    if (this.stnBuiltinsExports) {
+      return this.stnBuiltinsExports;
+    }
+
+    try {
+      // Load builtins.stn as a module
+      await this.moduleResolver.loadModule(
+        'builtins',
+        (source, opts) => this.parse(source, opts)
+      );
+
+      // Execute builtins.stn to get exports
+      const exports = await this.executeModule('builtins', {});
+      this.stnBuiltinsExports = exports || {};
+
+      console.log('📦 Loaded builtins.stn exports:', Object.keys(this.stnBuiltinsExports));
+      return this.stnBuiltinsExports;
+    } catch (error) {
+      console.error('Failed to load builtins.stn:', error);
+      return {};
+    }
+  }
+
+  // ========================================================================
+  // Parser API
+  // ========================================================================
+
+  /**
+   * Parse Stone source code into an Abstract Syntax Tree (AST)
+   *
+   * @param {string} source - Stone source code to parse
+   * @param {Object} [options={}] - Parse options
+   * @param {string} [options.filename='<stdin>'] - Filename for error messages
+   * @returns {Object} Parsed AST (Program node)
+   * @throws {Error} If parsing fails due to syntax errors
+   *
+   * @example
+   * const ast = service.parse('fn add(a, b) = a + b');
+   * // ast.type === 'Program'
+   * // ast.statements contains the function definition
+   */
+  parse(source, options = {}) {
+    const { filename = '<stdin>' } = options;
+
+    try {
+      const lexer = new Lexer(source, filename);
+      const tokens = lexer.tokenize();
+      const parser = new Parser(tokens, filename);
+      return parser.parse();
+    } catch (error) {
+      throw new Error(`Parse error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Tokenize source code
+   * @param {string} source - Stone source code
+   * @param {Object} options - Lexer options
+   * @returns {Array} Token array
+   */
+  tokenize(source, options = {}) {
+    const { filename = '<stdin>' } = options;
+    
+    try {
+      const lexer = new Lexer(source, filename);
+      return lexer.tokenize();
+    } catch (error) {
+      throw new Error(`Tokenize error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Validate syntax without building full AST
+   * @param {string} source - Stone source code
+   * @returns {Object} { valid: boolean, errors: Array }
+   */
+  validateSyntax(source) {
+    try {
+      this.parse(source);
+      return { valid: true, errors: [] };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [{ message: error.message, type: 'syntax' }]
+      };
+    }
+  }
+
+  /**
+   * Precheck Stone source code for syntax, type errors, AND imported modules
+   * Does not execute - only validates
+   * @param {string} source - Stone source code
+   * @param {Object} options - Options { filename }
+   * @returns {Promise<Object>} { valid: boolean, errors: [], warnings: [] }
+   */
+  async precheck(source, options = {}) {
+    const { filename = '<stdin>' } = options;
+    const errors = [];
+    const warnings = [];
+
+    try {
+      // 1. Parse (syntax check)
+      const ast = this.parse(source, { filename });
+
+      // 2. Load and validate imported modules (if any)
+      if (ast.imports && ast.imports.length > 0) {
+        const moduleErrors = await this.precheckModules(ast, filename);
+        errors.push(...moduleErrors);
+      }
+
+      // 3. Type check main file
+      const typeChecker = new TypeChecker({
+        moduleResolver: this.moduleResolver,
+        parser: (src, opts) => this.parse(src, opts),
+      });
+      const typeResult = typeChecker.check(ast);
+
+      if (!typeResult.success) {
+        // Preserve stage info from errors (already set in typeChecker)
+        errors.push(...typeResult.errors.map(err => ({
+          stage: err.stage || 'type_check',
+          type: err.type || 'type',
+          message: err.message,
+          location: err.location || null
+        })));
+      }
+
+      if (typeResult.warnings) {
+        warnings.push(...typeResult.warnings);
+      }
+
+      return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+      };
+    } catch (parseError) {
+      // Parse failed - preserve stage info if available
+      errors.push({
+        stage: parseError.stage || 'parse',
+        type: parseError.type || 'syntax',
+        message: parseError.message,
+        location: parseError.location || null
+      });
+
+      return {
+        valid: false,
+        errors,
+        warnings
+      };
+    }
+  }
+
+  /**
+   * Load and type-check all imported modules (without executing)
+   * @param {Object} ast - Parsed AST with imports
+   * @param {string} currentPath - Current file path for resolution
+   * @returns {Promise<Array>} Array of error objects
+   */
+  async precheckModules(ast, currentPath = null) {
+    const errors = [];
+    const visited = new Set();
+
+    if (currentPath) {
+      this.moduleResolver.setCurrentFilePath(currentPath);
+    }
+
+    for (const importNode of ast.imports || []) {
+      const modulePath = importNode.modulePath;
+
+      // Skip builtins and already visited
+      if (visited.has(modulePath)) continue;
+      if (this.moduleResolver.isBuiltinModule(modulePath)) continue;
+
+      visited.add(modulePath);
+
+      try {
+        // Load module AST (parse only, no execution)
+        const moduleData = await this.moduleResolver.loadModule(
+          modulePath,
+          (source, opts) => this.parse(source, opts)
+        );
+
+        if (moduleData.ast) {
+          // Recursively check module's imports
+          const nestedErrors = await this.precheckModules(moduleData.ast, modulePath);
+          errors.push(...nestedErrors);
+
+          // Type check the module
+          const typeChecker = new TypeChecker({
+            moduleResolver: this.moduleResolver,
+            parser: (src, opts) => this.parse(src, opts),
+          });
+          const typeResult = typeChecker.check(moduleData.ast);
+
+          if (!typeResult.success) {
+            errors.push(...typeResult.errors.map(err => ({
+              stage: err.stage || 'type_check',
+              type: err.type || 'type',
+              module: modulePath,
+              message: err.message,
+              location: err.location || null
+            })));
+          }
+        }
+      } catch (loadError) {
+        errors.push({
+          stage: loadError.stage || 'module_load',
+          type: loadError.type || 'module',
+          module: modulePath,
+          message: `Failed to load module '${modulePath}': ${loadError.message}`,
+          location: importNode.location || null
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  // ========================================================================
+  // Graph Building API
+  // ========================================================================
+
+  /**
+   * Build execution graph from source code
+   * @param {string} source - Stone source code
+   * @param {Object} nodeInserts - Node insert definitions
+   * @param {Object} options - Build options
+   * @returns {Object} Execution graph
+   */
+  buildGraph(source, nodeInserts, options = {}) {
+    try {
+      // Parse source to AST
+      const ast = this.parse(source, options);
+      
+      // Build graph from AST
+      return this.buildGraphFromAst(ast, nodeInserts, options);
+    } catch (error) {
+      throw new Error(`Build graph error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Build execution graph from AST
+   * @param {Object} ast - Abstract Syntax Tree
+   * @param {Object} nodeInserts - Node insert definitions
+   * @param {Object} options - Build options
+   * @returns {Object} Execution graph
+   */
+  buildGraphFromAst(ast, nodeInserts, options = {}) {
+    try {
+      // Build graph without caching to avoid circular reference issues
+      const graph = buildGraphFromAst(ast, nodeInserts);
+      return graph;
+    } catch (error) {
+      throw new Error(`Build graph from AST error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Build layout graph for visualization
+   * @param {Array} nodes - Graph nodes
+   * @returns {Object} Layout graph
+   */
+  buildLayoutGraph(nodes) {
+    try {
+      return buildLayoutGraph(nodes);
+    } catch (error) {
+      throw new Error(`Build layout graph error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Calculate layout for nodes
+   * @param {Array} nodes - Graph nodes
+   * @param {Object} config - Layout configuration
+   * @returns {Array} Nodes with layout positions
+   */
+  calculateLayout(nodes, config = {}) {
+    try {
+      const layoutGraph = this.buildLayoutGraph(nodes);
+      // Layout calculation would happen here
+      // For now, return the layout graph
+      return layoutGraph;
+    } catch (error) {
+      throw new Error(`Calculate layout error: ${error.message}`);
+    }
+  }
+
+  // ========================================================================
+  // Execution API
+  // ========================================================================
+
+  /**
+   * Execute a Stone script with full pipeline (type check, compile, run)
+   *
+   * This is the primary execution method that handles the complete execution flow:
+   * 1. Loads module dependencies if any imports exist
+   * 2. Performs type checking
+   * 3. Compiles to bytecode
+   * 4. Executes in the VM
+   *
+   * @param {string} fileId - Unique identifier for the file/script
+   * @param {Object} scriptGraph - Script graph containing AST or source reference
+   * @param {Object} [scriptGraph.ast] - Pre-parsed AST (optional)
+   * @param {Object} inputs - Input variables to inject into execution context
+   * @param {Object} [options={}] - Execution options
+   * @param {string} [options.source='unknown'] - Source identifier for tracking
+   * @param {string} [options.sourceCode] - Source code if AST not provided
+   * @param {string} [options.currentPath] - Current file path for module resolution
+   * @param {boolean} [options.debug=false] - Enable debug output
+   * @param {number} [options.maxIterations=100000] - Maximum loop iterations
+   * @returns {Promise<Object>} Execution result with output, variables, and metadata
+   *
+   * @example
+   * const result = await service.execute('script1', { ast }, { x: 10 });
+   * if (result.status === 'completed') {
+   *   console.log(result.output);
+   * }
+   */
+  async execute(fileId, scriptGraph, inputs, options = {}) {
+    const { source = 'unknown', sourceCode } = options;
+    const startTime = Date.now();
+
+    // Set up file system adapter for file module (if available)
+    if (this.fileSystemAdapter) {
+      setFileSystemAdapter(this.fileSystemAdapter);
+    }
+
+    try {
+      this.runningScripts.set(fileId, {
+        status: 'running',
+        startTime,
+        fileId,
+        source
+      });
+
+      let result;
+
+      const executionOptions = {
+        ...options,
+        variables: inputs || {},
+        debug: options.debug || false,
+        maxIterations: options.maxIterations || 100000,
+        moduleResolver: this.moduleResolver,
+      };
+
+      let ast;
+      if (scriptGraph.ast) {
+        ast = scriptGraph.ast;
+      } else if (sourceCode) {
+        ast = this.parse(sourceCode, { filename: fileId });
+      } else {
+        throw new Error('No AST or source code provided for execution');
+      }
+
+      // Clear dynamic overloads from previous executions
+      clearDynamicOverloads();
+
+      if (ast.imports && ast.imports.length > 0) {
+        this.clearModuleCache();
+        if (options.currentPath) {
+          this.moduleResolver.setCurrentFilePath(options.currentPath);
+        }
+        await this.loadModuleDependencies(ast, options.currentPath);
+        for (const importNode of ast.imports) {
+          const modulePath = importNode.modulePath;
+          if (!this.moduleResolver.isBuiltinModule(modulePath)) {
+            await this.executeModule(modulePath, executionOptions);
+          }
+        }
+      }
+
+      // Type check pass - resolves overloads and validates types before execution
+      // Pass moduleResolver and parser for static type analysis of imports
+      const typeChecker = new TypeChecker({
+        moduleResolver: this.moduleResolver,
+        parser: (source, opts) => this.parse(source, opts),
+      });
+      const typeResult = typeChecker.check(ast);
+
+      if (!typeResult.success) {
+        // Type errors found - return early with error info for UI to display
+        const endTime = Date.now();
+
+        // Format errors with stage info for terminal display
+        const typeErrors = typeResult.errors.map(err => {
+          const stage = err.stage ? `[${err.stage}] ` : '';
+          const loc = err.location
+            ? `[${err.location.line}:${err.location.column}] `
+            : '';
+          return `${stage}${loc}${err.message}`;
+        });
+
+        // Create terminal data with type error messages for Stone console display
+        const errorTerminalsData = {
+          main: {
+            type: 'console',
+            config: { title: 'Main', max_lines: 200 },
+            lines: ['TYPE ERROR', ...typeErrors]
+          }
+        };
+
+        const executionResult = {
+          fileId,
+          source,
+          output: typeErrors,
+          result: null,
+          variables: {},
+          terminalsData: errorTerminalsData,
+          startTime,
+          endTime,
+          duration: endTime - startTime,
+          status: 'error',
+          error: {
+            message: 'Type check failed',
+            errors: typeResult.errors, // Preserve full error objects with stage
+            stage: 'type_check'
+          },
+          metadata: {
+            requestSource: source,
+            inputs,
+            timestamp: new Date().toISOString(),
+            executionMode: 'vm'
+          }
+        };
+
+        this.executionResults.set(fileId, executionResult);
+        this.runningScripts.delete(fileId);
+        return executionResult;
+      }
+
+      // Load builtins (auto-imported functions like sin, cos, etc.)
+      const builtinsExports = await this.loadStnBuiltins();
+      const combinedVariables = { ...builtinsExports, ...(inputs || {}) };
+
+      // Execute using bytecode VM (unified execution path)
+      const vmResult = await this.executeWithVM(ast, {
+        ...executionOptions,
+        externalVars: combinedVariables,
+      });
+
+      // Build terminalsData: use adapter's terminalsData, and add main console if there's print output
+      let terminalsData = vmResult.terminalsData || {};
+      if (vmResult.output?.length > 0 && !terminalsData.main) {
+        terminalsData.main = {
+          type: 'console',
+          config: { title: 'Main', max_lines: 200 },
+          lines: vmResult.output
+        };
+      }
+
+      result = {
+        success: vmResult.success,
+        result: vmResult.result,
+        output: vmResult.output,
+        error: vmResult.error,
+        variables: {},
+        terminalsData,
+      };
+
+      const endTime = Date.now();
+      const output = result.output || result.result;
+
+      // Create result with metadata
+      const executionResult = {
+        fileId,
+        source,
+        output,
+        result: result.result,
+        variables: result.variables || {},
+        terminalsData: result.terminalsData || {},
+        startTime,
+        endTime,
+        duration: endTime - startTime,
+        status: result.success ? 'completed' : 'error',
+        error: result.error || null,
+        metadata: {
+          requestSource: source,
+          inputs,
+          timestamp: new Date().toISOString(),
+          executionMode: 'vm'
+        }
+      };
+
+      // Store result
+      this.executionResults.set(fileId, executionResult);
+      this.runningScripts.delete(fileId);
+
+      // Add to history
+      this._addToHistory(fileId, executionResult);
+
+      return executionResult;
+    } catch (error) {
+      const endTime = Date.now();
+
+      // Preserve stage info if available, otherwise infer from context
+      const stage = error.stage || 'parse';
+      const errorModule = error.module || null;
+
+      // Format error message with stage info for terminal
+      const errorMsg = `[${stage}]${errorModule ? ` in ${errorModule}:` : ''} ${error.message}`;
+
+      // Create terminal data with error message (errors here are typically parse/module errors before executor runs)
+      const errorTerminalsData = {
+        main: {
+          type: 'console',
+          config: { title: 'Main', max_lines: 200 },
+          lines: [errorMsg]
+        }
+      };
+
+      // Create error result
+      const result = {
+        fileId,
+        source,
+        output: null,
+        terminalsData: errorTerminalsData,
+        startTime,
+        endTime,
+        duration: endTime - startTime,
+        status: 'error',
+        error: {
+          message: error.message,
+          stage: stage,
+          module: errorModule,
+          location: error.location || null,
+          stack: error.stack
+        },
+        metadata: {
+          requestSource: source,
+          inputs,
+          timestamp: new Date().toISOString(),
+          executionMode: 'vm'
+        }
+      };
+
+      // Store error result
+      this.executionResults.set(fileId, result);
+      this.runningScripts.delete(fileId);
+
+      // Return result instead of throwing so terminal output is visible
+      return result;
+    }
+  }
+
+  /**
+   * Execute with callback for progress updates
+   * @param {string} fileId - File identifier
+   * @param {Object} scriptGraph - Execution graph
+   * @param {Array} inputs - Input values
+   * @param {Object} nodeInserts - Node insert definitions
+   * @param {Object} callbacks - Callback functions
+   * @returns {Promise<Object>} Execution result
+   */
+  async executeWithCallback(fileId, scriptGraph, inputs, nodeInserts, callbacks = {}) {
+    // TODO: Implement callback-based execution for progress tracking
+    return this.execute(fileId, scriptGraph, inputs, nodeInserts);
+  }
+
+  /**
+   * Execute using bytecode VM
+   * Compiles AST to bytecode and runs in the VM for faster execution
+   * @param {Object} ast - Parsed AST
+   * @param {Object} options - Execution options
+   * @param {Object} options.externalVars - External variables to inject
+   * @param {OutputAdapter} options.outputAdapter - Output adapter
+   * @returns {Promise<Object>} Execution result
+   */
+  async executeWithVM(ast, options = {}) {
+    const startTime = performance.now();
+    const adapter = options.outputAdapter || new BufferedOutputAdapter();
+    const externalVars = { ...(options.externalVars || {}) };
+
+    // Pre-scan for namespace imports to add them to externalVars
+    // This ensures the compiler knows about these variables
+    const namespaceImports = [];
+    for (const stmt of ast.statements || []) {
+      if (stmt.type === 'NamespaceImportStatement') {
+        // Use alias if provided, otherwise use the module name (last segment of path)
+        const alias = stmt.alias || stmt.modulePath.split('/').pop();
+        namespaceImports.push({
+          modulePath: stmt.modulePath,
+          alias
+        });
+        // Pre-register with null, will be populated after module loading
+        externalVars[alias] = null;
+      }
+    }
+
+    try {
+      // Get external variable names for compiler
+      const externalVarNames = Object.keys(externalVars);
+
+      // Create a new compiler instance with external var names
+      const compiler = new Compiler({
+        externalVarNames
+      });
+
+      // Compile AST to bytecode
+      const compiled = compiler.compile(ast);
+
+      if (!compiled.success) {
+        const errorMsg = compiled.errors.map(e => e.message).join('\n');
+        adapter.error(errorMsg, null);
+        adapter.finish(false, null);
+
+        // Include error in output and terminalsData for display
+        return {
+          success: false,
+          error: errorMsg,
+          output: [`Error: ${errorMsg}`],
+          result: null,
+          terminalsData: {
+            main: {
+              type: 'console',
+              config: { title: 'Main', max_lines: 200 },
+              lines: [`Error: ${errorMsg}`],
+            }
+          },
+          compilationTime: performance.now() - startTime,
+        };
+      }
+
+      const compileTime = performance.now() - startTime;
+
+      // Reset VM modules before loading (indices are relative to each execution)
+      this.vm.modules = [];
+      this.vm.moduleLocals = [];
+
+      // Load imported modules into VM before execution
+      // The compiler tracks imports in compiled.imports: [{ module: string, names: string[] }]
+      if (compiled.imports && compiled.imports.length > 0) {
+        for (const importInfo of compiled.imports) {
+          const modulePath = importInfo.module;
+          const importedNames = importInfo.names;
+
+          // Get module exports (from cache or builtin)
+          let moduleExports;
+
+          // Special handling for 'plots' module - needs runtime terminal constructors
+          if (modulePath === 'plots') {
+            // Create terminal constructors with the current adapter
+            const terminalConstructors = createTerminalConstructors({
+              outputAdapter: adapter,
+              terminalCounter: this.terminalCounter || 0
+            });
+            moduleExports = {
+              graph2d: terminalConstructors.graph2d,
+              graph3d: terminalConstructors.graph3d,
+              console_terminal: terminalConstructors.console_terminal
+            };
+          } else if (this.moduleResolver.isBuiltinModule(modulePath)) {
+            moduleExports = this.moduleResolver.getBuiltinModule(modulePath);
+          } else {
+            const cachedModule = this.moduleResolver.cache.get(modulePath);
+            moduleExports = cachedModule?.exports;
+          }
+
+          if (!moduleExports) {
+            throw new Error(`Module '${modulePath}' not found or not loaded`);
+          }
+
+          // Check if this is a namespace import (import module as alias)
+          if (importedNames.length === 1 && importedNames[0] === '*') {
+            // Namespace import - create namespace object with all exports
+            const namespaceObj = { ...moduleExports };
+            const exportsMap = new Map();
+            exportsMap.set('*', { slot: 0 });
+
+            // Store namespace object in moduleLocals for IMPORT_GET
+            const moduleStorage = [namespaceObj];
+
+            // Tag any CompiledFunctions in the namespace
+            const moduleIdx = this.vm.modules.length;
+            for (const value of Object.values(namespaceObj)) {
+              if (value instanceof CompiledFunction) {
+                this._tagFunctionWithModuleIdx(value, moduleIdx);
+              }
+            }
+
+            this.vm.modules.push({
+              id: modulePath,
+              exports: exportsMap,
+              initializer: null,
+            });
+            this.vm.moduleLocals.push(moduleStorage);
+
+            // Update externalVars with the actual namespace object
+            // The namespace was pre-registered as null, now populate it
+            const alias = importInfo.alias || modulePath.split('/').pop();
+            if (alias in externalVars) {
+              externalVars[alias] = namespaceObj;
+            }
+
+            continue;
+          }
+
+          // Create a module structure for the VM
+          // The VM expects: { id, exports: Map<name, {slot}>, initializer: null }
+          const exportsMap = new Map();
+          const moduleIdx = this.vm.modules.length;
+
+          // Get cached module data for proper upvalue resolution
+          const cachedModule = this.moduleResolver.cache.get(modulePath);
+          const allLocals = cachedModule?.allLocals || [];
+          const exportSlots = cachedModule?.exportSlots || {};
+          const compiledExports = cachedModule?.compiledExports || new Map();
+
+          // Use allLocals for moduleStorage to preserve original slot positions for upvalues
+          const moduleStorage = allLocals.length > 0 ? [...allLocals] : [];
+
+          // Selective imports (namespace imports handled above with continue)
+          for (let i = 0; i < importedNames.length; i++) {
+            const name = importedNames[i];
+            const value = moduleExports[name];
+            if (value === undefined && !(name in moduleExports)) {
+              throw new Error(`'${name}' is not exported from module '${modulePath}'`);
+            }
+
+            // Use full export info from compiledExports if available (preserves overload info)
+            const fullExportInfo = compiledExports.get(name);
+            if (fullExportInfo) {
+              exportsMap.set(name, fullExportInfo);
+            } else {
+              // Fall back to cached export slot if available, otherwise use sequential slot
+              const originalSlot = exportSlots[name] !== undefined ? exportSlots[name] : i;
+              exportsMap.set(name, { slot: originalSlot });
+            }
+
+            // If no allLocals, store at sequential slot
+            if (allLocals.length === 0) {
+              moduleStorage[i] = value;
+            }
+
+            // Tag CompiledFunctions with moduleIdx (including nested functions in constants)
+            if (value instanceof CompiledFunction) {
+              this._tagFunctionWithModuleIdx(value, moduleIdx);
+            }
+          }
+
+          // Tag all functions in allLocals with moduleIdx
+          for (const value of moduleStorage) {
+            if (value instanceof CompiledFunction) {
+              this._tagFunctionWithModuleIdx(value, moduleIdx);
+            }
+          }
+
+          // Load into VM
+          this.vm.modules.push({
+            id: modulePath,
+            exports: exportsMap,
+            initializer: null,
+          });
+          this.vm.moduleLocals.push(moduleStorage);
+        }
+      }
+
+      // Execute bytecode with adapter and external variables
+      const execStart = performance.now();
+      const result = await this.vm.execute(compiled, {
+        outputAdapter: adapter,
+        externalVars
+      });
+      const execTime = performance.now() - execStart;
+
+      // Capture all locals for module caching (needed for closure upvalues)
+      const localCount = compiled.main?.localCount || 0;
+      const allLocals = [];
+      for (let i = 0; i < localCount; i++) {
+        allLocals[i] = this.vm.locals[i];
+      }
+
+      // Get output from adapter (print output goes to adapter, not vmResult.output)
+      const adapterOutput = adapter.getOutput();
+
+      // If there's an error, ensure it's added to the main console terminal
+      if (!result.success && result.error) {
+        // Ensure terminalsData exists
+        if (!adapterOutput.terminalsData) {
+          adapterOutput.terminalsData = {};
+        }
+        // Ensure main console exists
+        if (!adapterOutput.terminalsData.main) {
+          adapterOutput.terminalsData.main = {
+            type: 'console',
+            config: { title: 'Main', max_lines: 200 },
+            lines: []
+          };
+        }
+        // Add error to main console lines
+        const errorLine = `Error: ${result.error}`;
+        if (!adapterOutput.terminalsData.main.lines) {
+          adapterOutput.terminalsData.main.lines = [];
+        }
+        // Only add if not already present (avoid duplicates)
+        if (!adapterOutput.terminalsData.main.lines.includes(errorLine)) {
+          adapterOutput.terminalsData.main.lines.push(errorLine);
+        }
+      }
+
+      // Debug logging for terminal data
+      console.log('[StoneEngineService.executeWithVM] terminalsData keys:', Object.keys(adapterOutput.terminalsData || {}));
+      if (adapterOutput.terminalsData) {
+        for (const [termId, termData] of Object.entries(adapterOutput.terminalsData)) {
+          const firstPlot = termData.plots?.[0];
+          console.log(`[StoneEngineService.executeWithVM] Terminal ${termId}:`, {
+            type: termData.type,
+            hasPlots: !!termData.plots,
+            plotsLength: termData.plots?.length,
+            firstPlot: firstPlot ? {
+              type: firstPlot.type,
+              label: firstPlot.label,
+              x: firstPlot.x,
+              xType: firstPlot.x?.constructor?.name,
+              xSize: firstPlot.x?.size,
+              xLength: firstPlot.x?.length,
+              xData: firstPlot.x?.data,
+              y: firstPlot.y,
+              yType: firstPlot.y?.constructor?.name,
+              ySize: firstPlot.y?.size,
+              yLength: firstPlot.y?.length,
+              yData: firstPlot.y?.data,
+            } : null
+          });
+        }
+      }
+
+      return {
+        success: result.success,
+        result: result.result,
+        output: adapterOutput.output,
+        terminalsData: adapterOutput.terminalsData,
+        error: result.error,
+        exports: result.exports,  // Pass through exports from VM
+        exportSlots: result.exportSlots,  // Original slot positions for exports
+        compiledExports: compiled.exports,  // Full export info including overload data
+        allLocals,  // All locals for module caching
+        compilationTime: compileTime,
+        executionTime: execTime,
+        totalTime: compileTime + execTime,
+      };
+    } catch (e) {
+      adapter.error(e.message, null);
+      adapter.finish(false, e);
+
+      // Include error in output and terminalsData for display
+      return {
+        success: false,
+        error: e.message,
+        output: [`Error: ${e.message}`],
+        result: null,
+        terminalsData: {
+          main: {
+            type: 'console',
+            config: { title: 'Main', max_lines: 200 },
+            lines: [`Error: ${e.message}`],
+          }
+        },
+        totalTime: performance.now() - startTime,
+      };
+    }
+  }
+
+  /**
+   * Compile and execute source code using VM
+   * Includes parsing, type checking, compilation, and execution
+   * @param {string} source - Stone source code
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Execution result with timing info
+   */
+  async compileAndExecute(source, options = {}) {
+    const { filename = '<stdin>' } = options;
+    const startTime = performance.now();
+
+    try {
+      // Parse
+      const parseStart = performance.now();
+      const ast = this.parse(source, { filename });
+      const parseTime = performance.now() - parseStart;
+
+      // Type check
+      const typeStart = performance.now();
+      const typeChecker = new TypeChecker({ moduleResolver: this.moduleResolver });
+      const typeResult = typeChecker.check(ast);
+      const typeTime = performance.now() - typeStart;
+
+      if (!typeResult.success) {
+        return {
+          success: false,
+          error: 'Type check failed: ' + typeResult.errors.map(e => e.message).join('; '),
+          parseTime,
+          typeCheckTime: typeTime,
+        };
+      }
+
+      // Compile and execute
+      const vmResult = await this.executeWithVM(ast, options);
+
+      return {
+        ...vmResult,
+        parseTime,
+        typeCheckTime: typeTime,
+      };
+    } catch (e) {
+      return {
+        success: false,
+        error: e.message,
+        totalTime: performance.now() - startTime,
+      };
+    }
+  }
+
+  /**
+   * Pause script execution
+   * @param {string} fileId - File identifier
+   */
+  pause(fileId) {
+    const state = this.runningScripts.get(fileId);
+    if (state) {
+      state.status = 'paused';
+    }
+  }
+
+  /**
+   * Resume script execution
+   * @param {string} fileId - File identifier
+   */
+  resume(fileId) {
+    const state = this.runningScripts.get(fileId);
+    if (state && state.status === 'paused') {
+      state.status = 'running';
+    }
+  }
+
+  /**
+   * Stop script execution
+   * @param {string} fileId - File identifier
+   */
+  stop(fileId) {
+    this.runningScripts.delete(fileId);
+  }
+
+  // ========================================================================
+  // Storage API
+  // ========================================================================
+
+  /**
+   * Store execution result
+   * @param {string} fileId - File identifier
+   * @param {string} source - Source code
+   * @param {Object} result - Execution result
+   * @param {Object} metadata - Additional metadata
+   */
+  storeExecutionResult(fileId, source, result, metadata = {}) {
+    const executionData = {
+      fileId,
+      source,
+      result,
+      metadata: {
+        ...metadata,
+        executedAt: new Date().toISOString()
+      }
+    };
+
+    this.executionResults.set(fileId, executionData);
+    this._addToHistory(fileId, executionData);
+  }
+
+  /**
+   * Get execution history for a file
+   * @param {string} fileId - File identifier
+   * @param {number} limit - Maximum number of results
+   * @returns {Array} Execution history
+   */
+  getExecutionHistory(fileId, limit = 10) {
+    const history = this.executionHistory.get(fileId) || [];
+    return history.slice(0, limit);
+  }
+
+  /**
+   * Get stored source code
+   * @param {string} fileId - File identifier
+   * @returns {string|null} Source code
+   */
+  getStoredSource(fileId) {
+    const result = this.executionResults.get(fileId);
+    return result?.source || null;
+  }
+
+  /**
+   * Get stored result
+   * @param {string} fileId - File identifier
+   * @returns {Object|null} Execution result
+   */
+  getStoredResult(fileId) {
+    return this.executionResults.get(fileId) || null;
+  }
+
+  /**
+   * Clear stored data for a file
+   * @param {string} fileId - File identifier
+   */
+  clearStoredData(fileId) {
+    this.executionResults.delete(fileId);
+    this.executionHistory.delete(fileId);
+    this.runningScripts.delete(fileId);
+  }
+
+  /**
+   * List all stored executions
+   * @returns {Array} Array of file IDs with stored data
+   */
+  listStoredExecutions() {
+    return Array.from(this.executionResults.keys());
+  }
+
+  // ========================================================================
+  // Caching API
+  // ========================================================================
+
+  /**
+   * Get cached AST
+   * @param {string} sourceHash - Source code hash
+   * @returns {Object|null} Cached AST
+   */
+  getCachedAst(sourceHash) {
+    return this.astCache.get(sourceHash) || null;
+  }
+
+  /**
+   * Set cached AST
+   * @param {string} sourceHash - Source code hash
+   * @param {Object} ast - AST to cache
+   */
+  setCachedAst(sourceHash, ast) {
+    this._manageCacheSize(this.astCache);
+    this.astCache.set(sourceHash, ast);
+  }
+
+  /**
+   * Get cached graph
+   * @param {string} sourceHash - Source code hash
+   * @param {string} nodeInsertsHash - Node inserts hash
+   * @returns {Object|null} Cached graph
+   */
+  getCachedGraph(sourceHash, nodeInsertsHash) {
+    const cacheKey = `${sourceHash}_${nodeInsertsHash}`;
+    return this.graphCache.get(cacheKey) || null;
+  }
+
+  /**
+   * Set cached graph
+   * @param {string} sourceHash - Source code hash
+   * @param {string} nodeInsertsHash - Node inserts hash
+   * @param {Object} graph - Graph to cache
+   */
+  setCachedGraph(sourceHash, nodeInsertsHash, graph) {
+    this._manageCacheSize(this.graphCache);
+    const cacheKey = `${sourceHash}_${nodeInsertsHash}`;
+    this.graphCache.set(cacheKey, graph);
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache() {
+    this.astCache.clear();
+    this.graphCache.clear();
+  }
+
+  // ========================================================================
+  // Utility API
+  // ========================================================================
+
+  /**
+   * Get execution state for a file
+   * @param {string} fileId - File identifier
+   * @returns {Object|null} Execution state
+   */
+  getExecutionState(fileId) {
+    return this.runningScripts.get(fileId) || null;
+  }
+
+  /**
+   * Reset service state
+   */
+  reset() {
+    this.runningScripts.clear();
+    this.executionResults.clear();
+    this.executionHistory.clear();
+    this.clearCache();
+    this.clearModuleCache();
+  }
+
+  /**
+   * Get all errors from recent executions
+   * @returns {Array} Array of errors
+   */
+  getErrors() {
+    const errors = [];
+    for (const [fileId, result] of this.executionResults.entries()) {
+      if (result.status === 'error' && result.error) {
+        errors.push({
+          fileId,
+          error: result.error,
+          timestamp: result.metadata?.timestamp
+        });
+      }
+    }
+    return errors;
+  }
+
+  /**
+   * Validate graph structure
+   * @param {Object} graph - Graph to validate
+   * @returns {Object} { valid: boolean, errors: Array }
+   */
+  validateGraph(graph) {
+    const errors = [];
+
+    if (!graph || !graph.nodes) {
+      errors.push({ message: 'Graph must have nodes array', type: 'structure' });
+    }
+
+    if (!graph.edges) {
+      errors.push({ message: 'Graph must have edges array', type: 'structure' });
+    }
+
+    // Additional validation logic here
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  // ========================================================================
+  // Module System API
+  // ========================================================================
+
+  /**
+   * Configure the file system source for module resolution
+   * @param {Map|Array} filesSource - Map or Array of file objects from FileSystemContext
+   */
+  setFilesSource(filesSource) {
+    this.filesSource = filesSource;
+    this.moduleResolver.setFilesSource(filesSource);
+  }
+
+  /**
+   * Configure the file loader function for module resolution
+   * @param {Function} loader - Function that takes fileId and returns file content
+   */
+  setFileLoader(loader) {
+    this.fileLoader = loader;
+    this.moduleResolver.setFileLoader(loader);
+  }
+
+  /**
+   * Configure the file system adapter for the file module
+   * @param {Object} adapter - Object with readFile(path) and writeFile(path, content) methods
+   */
+  setFileSystemAdapter(adapter) {
+    this.fileSystemAdapter = adapter;
+  }
+
+  setCurrentFilePath(path) {
+    this.moduleResolver.setCurrentFilePath(path);
+  }
+
+  async loadModuleDependencies(ast, currentFilePath = null, visited = new Set()) {
+    if (currentFilePath) {
+      this.moduleResolver.setCurrentFilePath(currentFilePath);
+    }
+
+    // Collect all module paths to load (from imports and re-exports)
+    const modulesToLoad = [];
+
+    // Add import dependencies
+    for (const importNode of ast.imports || []) {
+      modulesToLoad.push(importNode.modulePath);
+    }
+
+    // Add re-export source modules
+    for (const exportNode of ast.exports || []) {
+      if (exportNode.type === 'SelectiveReExportStatement' || exportNode.type === 'NamespaceReExportStatement') {
+        modulesToLoad.push(exportNode.modulePath);
+      }
+    }
+
+    // Load all modules
+    for (const modulePath of modulesToLoad) {
+      if (visited.has(modulePath)) continue;
+      if (this.moduleResolver.isBuiltinModule(modulePath)) continue;
+      if (this.moduleResolver.cache.has(modulePath)) continue;
+
+      visited.add(modulePath);
+
+      const moduleData = await this.moduleResolver.loadModule(
+        modulePath,
+        (source, options) => this.parse(source, options)
+      );
+
+      if (moduleData.ast && moduleData.fileId) {
+        const depModulePath = buildFilePath(moduleData.fileId, this.filesSource);
+        await this.loadModuleDependencies(moduleData.ast, depModulePath, visited);
+      }
+    }
+  }
+
+  async executeModule(modulePath, options = {}) {
+    const cachedModule = this.moduleResolver.cache.get(modulePath);
+    if (cachedModule && cachedModule.exports) {
+      return cachedModule.exports;
+    }
+
+    if (this.moduleResolver.isBuiltinModule(modulePath)) {
+      return this.moduleResolver.getBuiltinModule(modulePath);
+    }
+
+    if (!cachedModule) {
+      await this.moduleResolver.loadModule(
+        modulePath,
+        (source, opts) => this.parse(source, opts)
+      );
+    }
+
+    const moduleData = this.moduleResolver.cache.get(modulePath);
+    if (!moduleData || !moduleData.ast) {
+      throw new Error(`Failed to load module: ${modulePath}`);
+    }
+
+    const moduleFilePath = moduleData.fileId ? buildFilePath(moduleData.fileId, this.filesSource) : modulePath;
+    await this.loadModuleDependencies(moduleData.ast, moduleFilePath);
+
+    // Execute import dependencies
+    for (const importNode of moduleData.ast.imports || []) {
+      const depPath = importNode.modulePath;
+      if (!this.moduleResolver.isBuiltinModule(depPath)) {
+        const depModule = this.moduleResolver.cache.get(depPath);
+        if (depModule && !depModule.exports && depModule.ast) {
+          await this.executeModule(depPath, options);
+        }
+      }
+    }
+
+    // Execute re-export source modules
+    for (const exportNode of moduleData.ast.exports || []) {
+      if (exportNode.type === 'SelectiveReExportStatement' || exportNode.type === 'NamespaceReExportStatement') {
+        const depPath = exportNode.modulePath;
+        if (!this.moduleResolver.isBuiltinModule(depPath)) {
+          // Modules are cached under their raw paths
+          const depModule = this.moduleResolver.cache.get(depPath);
+          if (depModule && !depModule.exports && depModule.ast) {
+            await this.executeModule(depPath, options);
+          }
+        }
+      }
+    }
+
+    // Type check module before execution
+    // Pass moduleResolver and parser for static type analysis of imports
+    const typeChecker = new TypeChecker({
+      moduleResolver: this.moduleResolver,
+      parser: (source, opts) => this.parse(source, opts),
+    });
+    const typeResult = typeChecker.check(moduleData.ast);
+
+    if (!typeResult.success) {
+      // Print detailed type errors to console
+      console.error('\n\x1b[31m╔══════════════════════════════════════════════════════════════╗\x1b[0m');
+      console.error('\x1b[31m║                      TYPE ERROR                              ║\x1b[0m');
+      console.error('\x1b[31m╚══════════════════════════════════════════════════════════════╝\x1b[0m\n');
+      console.error(`\x1b[33mModule:\x1b[0m ${modulePath}\n`);
+
+      for (const err of typeResult.errors) {
+        const loc = err.location
+          ? `\x1b[36m${modulePath}:${err.location.line}:${err.location.column}\x1b[0m`
+          : `\x1b[36m${modulePath}\x1b[0m`;
+        console.error(`${loc}`);
+        console.error(`\x1b[31mError:\x1b[0m ${err.message}\n`);
+      }
+
+      const errorMessages = typeResult.errors.map(err => {
+        const loc = err.location ? `[${err.location.line}:${err.location.column}] ` : '';
+        return `${loc}${err.message}`;
+      }).join('\n');
+      const error = new Error(`Type check failed in module '${modulePath}':\n${errorMessages}`);
+      error.stage = 'type_check';
+      error.type = 'type';
+      error.module = modulePath;
+      error.errors = typeResult.errors;
+      throw error;
+    }
+
+    // Execute module using bytecode VM
+    const vmResult = await this.executeWithVM(moduleData.ast, {
+      ...options,
+      externalVars: options.variables || {},
+    });
+
+    if (!vmResult.success) {
+      // Format error properly - may be string or array
+      const errorMsg = Array.isArray(vmResult.error)
+        ? vmResult.error.join('\n')
+        : vmResult.error;
+      const error = new Error(`Error executing module '${modulePath}': ${errorMsg}`);
+      error.stage = 'execute';
+      error.module = modulePath;
+      throw error;
+    }
+
+    const exports = vmResult.exports || {};
+
+    // Resolve re-exports to actual values
+    await this.resolveReExports(exports, modulePath, options);
+
+    // Cache exports, allLocals, and exportSlots for later import resolution
+    moduleData.exports = exports;
+    moduleData.allLocals = vmResult.allLocals || [];
+    moduleData.exportSlots = vmResult.exportSlots || {};
+    moduleData.compiledExports = vmResult.compiledExports || new Map();
+
+    // Register complex module's arithmetic functions as dynamic overloads
+    // This enables operators (+, -, *, /, etc.) to work with complex numbers
+    if (modulePath === 'complex') {
+      this._registerComplexOverloads(exports, moduleData.allLocals, moduleData.compiledExports);
+    }
+
+    return exports;
+  }
+
+  /**
+   * Register complex module's arithmetic functions as dynamic overloads.
+   * This allows the VM's operator handlers to dispatch to Stone functions
+   * for complex number operations.
+   */
+  _registerComplexOverloads(exports, allLocals, compiledExports) {
+    const binaryOps = [
+      { name: 'add', sig: { in: ['complex', 'complex'], out: 'complex' } },
+      { name: 'sub', sig: { in: ['complex', 'complex'], out: 'complex' } },
+      { name: 'mul', sig: { in: ['complex', 'complex'], out: 'complex' } },
+      { name: 'div', sig: { in: ['complex', 'complex'], out: 'complex' } },
+      { name: 'pow', sig: { in: ['complex', 'complex'], out: 'complex' } },
+    ];
+
+    const unaryOps = [
+      { name: 'neg', sig: { in: ['complex'], out: 'complex' } },
+    ];
+
+    const allOps = [...binaryOps, ...unaryOps];
+
+    for (const { name, sig } of allOps) {
+      const fn = exports[name];
+      if (fn instanceof CompiledFunction) {
+        registerOverload(name, fn, sig);
+      } else {
+        const exportInfo = compiledExports.get(name);
+        if (exportInfo && allLocals[exportInfo.slot] instanceof CompiledFunction) {
+          registerOverload(name, allLocals[exportInfo.slot], sig);
+        }
+      }
+    }
+  }
+
+  /**
+   * Resolve re-export metadata to actual values
+   * Re-exports are stored as { _isReExport: true, _sourceName, _sourceModule, ... }
+   * This method replaces them with the actual exported values from the source modules
+   */
+  async resolveReExports(exports, currentModulePath, options = {}) {
+    for (const [exportName, exportValue] of Object.entries(exports)) {
+      if (exportValue && exportValue._isReExport) {
+        const { _reExportType, _sourceName, _sourceModule } = exportValue;
+
+        // Source modules should already be loaded and executed at this point
+        // They are cached under their raw paths (e.g., './test_modules_math')
+        // Also check builtin modules (like 'primitives') which are not in the cache
+        let sourceModule = this.moduleResolver.cache.get(_sourceModule);
+        let sourceExports = sourceModule?.exports;
+
+        // Check if it's a builtin module (like 'primitives')
+        if (!sourceExports && this.moduleResolver.isBuiltinModule(_sourceModule)) {
+          sourceExports = this.moduleResolver.getBuiltinModule(_sourceModule);
+        }
+
+        if (!sourceExports) {
+          throw new Error(`Re-export failed: source module '${_sourceModule}' not found or not executed`);
+        }
+
+        if (_reExportType === 'selective') {
+          // Get specific export from source module
+          if (!(_sourceName in sourceExports)) {
+            throw new Error(`Re-export failed: '${_sourceName}' is not exported from '${_sourceModule}'`);
+          }
+          exports[exportName] = sourceExports[_sourceName];
+        } else if (_reExportType === 'namespace') {
+          // Re-export entire module as namespace
+          exports[exportName] = Object.freeze({ ...sourceExports });
+        }
+
+        console.log(`📤 Resolved re-export '${exportName}' from '${_sourceModule}':`, typeof exports[exportName]);
+      }
+    }
+  }
+
+  async executeWithModules(source, options = {}) {
+    const { currentPath = null, variables = {} } = options;
+
+    // Clear dynamic overloads from previous executions
+    clearDynamicOverloads();
+
+    const ast = this.parse(source, { filename: currentPath || '<stdin>' });
+
+    if (currentPath) {
+      this.moduleResolver.setCurrentFilePath(currentPath);
+    }
+
+    await this.loadModuleDependencies(ast, currentPath);
+
+    for (const importNode of ast.imports || []) {
+      const modulePath = importNode.modulePath;
+      if (!this.moduleResolver.isBuiltinModule(modulePath)) {
+        await this.executeModule(modulePath, options);
+      }
+    }
+
+    // Type check before execution
+    // Pass moduleResolver and parser for static type analysis of imports
+    const typeChecker = new TypeChecker({
+      moduleResolver: this.moduleResolver,
+      parser: (source, opts) => this.parse(source, opts),
+    });
+    const typeResult = typeChecker.check(ast);
+
+    if (!typeResult.success) {
+      // Print detailed type errors to console
+      const fileName = currentPath || '<stdin>';
+      console.error('\n\x1b[31m╔══════════════════════════════════════════════════════════════╗\x1b[0m');
+      console.error('\x1b[31m║                      TYPE ERROR                              ║\x1b[0m');
+      console.error('\x1b[31m╚══════════════════════════════════════════════════════════════╝\x1b[0m\n');
+
+      for (const err of typeResult.errors) {
+        const loc = err.location
+          ? `\x1b[36m${fileName}:${err.location.line}:${err.location.column}\x1b[0m`
+          : `\x1b[36m${fileName}\x1b[0m`;
+        console.error(`${loc}`);
+        console.error(`\x1b[31mError:\x1b[0m ${err.message}\n`);
+      }
+
+      const errorMessages = typeResult.errors.map(err => {
+        const loc = err.location ? `[${err.location.line}:${err.location.column}] ` : '';
+        return `${loc}${err.message}`;
+      });
+      return {
+        success: false,
+        error: 'Type check failed',
+        output: errorMessages,
+        variables: {},
+      };
+    }
+
+    // Execute using bytecode VM
+    const vmResult = await this.executeWithVM(ast, {
+      ...options,
+      externalVars: variables,
+    });
+
+    return {
+      success: vmResult.success,
+      result: vmResult.result,
+      output: vmResult.output,
+      terminalsData: vmResult.terminalsData,  // Include terminal data (plots, etc.)
+      error: vmResult.error,
+      variables: {},
+      exports: vmResult.exports || {},
+    };
+  }
+
+  /**
+   * Clear the module cache
+   */
+  clearModuleCache() {
+    this.moduleResolver.clearCache();
+  }
+
+  /**
+   * Get the module resolver instance
+   * @returns {ModuleResolver}
+   */
+  getModuleResolver() {
+    return this.moduleResolver;
+  }
+
+  // ========================================================================
+  // Private Helper Methods
+  // ========================================================================
+
+  /**
+   * Add execution to history
+   * @private
+   */
+  _addToHistory(fileId, executionData) {
+    if (!this.executionHistory.has(fileId)) {
+      this.executionHistory.set(fileId, []);
+    }
+
+    const history = this.executionHistory.get(fileId);
+    history.unshift(executionData);
+
+    // Limit history size
+    if (history.length > this.maxHistoryPerFile) {
+      history.pop();
+    }
+  }
+
+  /**
+   * Manage cache size (LRU eviction)
+   * @private
+   */
+  _manageCacheSize(cache) {
+    if (cache.size >= this.maxCacheSize) {
+      // Remove oldest entry (first key)
+      const firstKey = cache.keys().next().value;
+      cache.delete(firstKey);
+    }
+  }
+
+  /**
+   * Hash a string
+   * @private
+   */
+  _hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash; // Convert to 32-bit integer
+    }
+    return hash.toString(36);
+  }
+
+  /**
+   * Hash an object
+   * @private
+   */
+  _hashObject(obj) {
+    try {
+      // Use a simpler hash for large objects to avoid "Invalid string length" errors
+      const str = JSON.stringify(obj);
+      return this._hashString(str);
+    } catch (error) {
+      // If JSON.stringify fails (circular reference or too large), use a fallback
+      console.warn('Failed to hash object, using fallback:', error.message);
+      return this._hashString(String(Date.now()) + String(Math.random()));
+    }
+  }
+}
+
+// Export singleton instance
+export const stoneEngineService = new StoneEngineService();
+
+// Export class for testing
+export { StoneEngineService };