stone-lang 0.1.0

package/StoneEngine.js

@@ -0,0 +1,879 @@
+/**
+ * StoneEngine - Platform-agnostic Stone execution engine
+ *
+ * Provides a thin wrapper around the Stone compiler/VM/AST executor.
+ * Uses OutputAdapter for streaming output and FileSystemAdapter for file access.
+ *
+ * This engine is designed to work identically in:
+ * - CLI (with CLIOutputAdapter)
+ * - Web app (with WebOutputAdapter)
+ * - Daemon (with JSON streaming adapter)
+ *
+ * Usage:
+ *   const engine = new StoneEngine({
+ *     outputAdapter: new CLIOutputAdapter(),
+ *     fileSystemAdapter: new NodeFileSystemAdapter(),
+ *   });
+ *
+ *   const result = await engine.execute(sourceCode, { filename: 'script.stn' });
+ */
+
+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 { Compiler } from './backends/js-vm/compiler.js';
+import { VM } from './backends/js-vm/vm/index.js';
+import { CompiledFunction } from './backends/js-vm/bytecode.js';
+import { BufferedOutputAdapter } from './adapters/OutputAdapter.js';
+import { createTerminalConstructors } from './frontend/parsing/terminal-registry.js';
+import { createTreeShaker } from './frontend/analysis/treeShaker.js';
+import { setFileSystemAdapter } from './backends/js-vm/primitives/file.js';
+import { registerOverload, clearDynamicOverloads } from './backends/js-vm/primitives/overloads.js';
+
+export class StoneEngine {
+  /**
+   * Create a new Stone engine instance
+   * @param {Object} options - Engine configuration
+   * @param {OutputAdapter} options.outputAdapter - Output adapter for streaming
+   * @param {FileSystemAdapter} options.fileSystemAdapter - File system adapter
+   * @param {boolean} options.debug - Enable debug logging
+   */
+  constructor(options = {}) {
+    this.outputAdapter = options.outputAdapter || null;
+    this.fileSystemAdapter = options.fileSystemAdapter || null;
+    this.debug = options.debug || false;
+
+    // Core components
+    this.compiler = new Compiler();
+    this.vm = new VM();
+    this.moduleResolver = new ModuleResolver();
+
+    // Configure module resolver with file system adapter
+    if (this.fileSystemAdapter) {
+      this.moduleResolver.setFileLoader(async (modulePath) => {
+        return this.fileSystemAdapter.readFile(modulePath);
+      });
+    }
+
+    // Cached builtins.stn exports
+    this.stnBuiltinsExports = null;
+  }
+
+  /**
+   * Set the output adapter
+   * @param {OutputAdapter} adapter
+   */
+  setOutputAdapter(adapter) {
+    this.outputAdapter = adapter;
+  }
+
+  /**
+   * Set the file system adapter
+   * @param {FileSystemAdapter} adapter
+   */
+  setFileSystemAdapter(adapter) {
+    this.fileSystemAdapter = adapter;
+    if (adapter) {
+      this.moduleResolver.setFileLoader(async (modulePath) => {
+        return adapter.readFile(modulePath);
+      });
+    }
+  }
+
+  /**
+   * Set the package context for stone_modules resolution
+   * @param {PackageContext} context
+   */
+  setPackageContext(context) {
+    this.moduleResolver.setPackageContext(context);
+  }
+
+  /**
+   * Recursively tag a CompiledFunction and its nested functions with moduleIdx
+   * This is needed for proper upvalue resolution when functions are called from different contexts
+   * @param {CompiledFunction} fn - The function to tag
+   * @param {number} moduleIdx - The module index
+   * @param {Set} visited - Set of 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);
+        }
+      }
+    }
+  }
+
+  /**
+   * Parse source code to AST
+   * @param {string} source - Stone source code
+   * @param {Object} options - Parse options
+   * @returns {Object} AST
+   */
+  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}`);
+    }
+  }
+
+  /**
+   * Type check an AST
+   * @param {Object} ast - AST to check
+   * @param {Object} options - Type check options
+   * @returns {Object} Type check result { success, errors }
+   */
+  typeCheck(ast, options = {}) {
+    const typeChecker = new TypeChecker({
+      moduleResolver: this.moduleResolver,
+      parser: (source, opts) => this.parse(source, opts),
+      ...options,
+    });
+
+    return typeChecker.check(ast);
+  }
+
+  /**
+   * Precheck Stone source code for syntax and type errors
+   * Does not execute - only validates
+   * @param {string} source - Stone source code
+   * @param {Object} options - Options { filename }
+   * @returns {Object} { valid: boolean, errors: [], warnings: [] }
+   */
+  precheck(source, options = {}) {
+    const { filename = '<stdin>' } = options;
+    const errors = [];
+    const warnings = [];
+
+    try {
+      // 1. Parse (syntax check)
+      const ast = this.parse(source, { filename });
+
+      // 2. Type check
+      const typeResult = this.typeCheck(ast, options);
+
+      if (!typeResult.success) {
+        errors.push(...typeResult.errors.map(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 - syntax error
+      errors.push({
+        type: 'syntax',
+        message: parseError.message,
+        location: null
+      });
+
+      return {
+        valid: false,
+        errors,
+        warnings
+      };
+    }
+  }
+
+  /**
+   * Analyze imports in an AST for tree shaking optimization
+   * Returns information about which exports are used from each module,
+   * and detects unused imports.
+   *
+   * @param {Object} ast - AST to analyze
+   * @returns {Object} Analysis result
+   * @returns {Map<string, Set<string>>} result.usedExports - Map from module path to used export names
+   * @returns {Array} result.unusedImports - Array of { localName, modulePath, importedName }
+   * @returns {boolean} result.hasUnusedImports - True if there are unused imports
+   * @returns {Function} result.filterExports - Function to filter module exports
+   */
+  analyzeImports(ast) {
+    const shaker = createTreeShaker(ast);
+    return {
+      usedExports: shaker.usedExports,
+      unusedImports: shaker.unusedImports,
+      hasUnusedImports: shaker.unusedImports.length > 0,
+      filterExports: shaker.filterExports,
+    };
+  }
+
+  /**
+   * Execute Stone source code
+   * @param {string} source - Stone source code
+   * @param {Object} options - Execution options
+   * @param {string} options.filename - Source filename (for error reporting)
+   * @param {Object} options.variables - Initial variable bindings
+   * @param {string} options.currentPath - Current file path (for module resolution)
+   * @param {OutputAdapter} options.outputAdapter - Override output adapter for this execution
+   * @param {number} options.maxIterations - Maximum loop iterations
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(source, options = {}) {
+    const {
+      filename = '<stdin>',
+      variables = {},
+      currentPath = null,
+      maxIterations = 100000,
+    } = options;
+
+    // Use per-execution adapter override or instance adapter
+    // If neither, create a buffered adapter for backward compat
+    const adapter = options.outputAdapter || this.outputAdapter || new BufferedOutputAdapter();
+    const startTime = Date.now();
+
+    // Clear dynamic overloads from previous executions
+    // This ensures a clean slate for each execution
+    clearDynamicOverloads();
+
+    // Set up file system adapter for file module (if available)
+    if (this.fileSystemAdapter) {
+      setFileSystemAdapter(this.fileSystemAdapter);
+    }
+
+    if (this.debug) {
+      console.log('[StoneEngine] Starting execution:', filename);
+    }
+
+    try {
+      // 1. Parse
+      if (this.debug) console.log('[StoneEngine] Step 1: Parsing...');
+      const ast = this.parse(source, { filename });
+      if (this.debug) {
+        console.log('[StoneEngine] Parsed successfully, statements:', ast.statements?.length);
+        console.log('[StoneEngine] Imports:', ast.imports?.map(i => i.modulePath));
+      }
+
+      // 2. Set up module resolution
+      // Use full file path for package resolution
+      // Handle cases where filename is already an absolute path
+      let fullFilePath;
+      if (filename.includes('/') || filename.includes('\\')) {
+        // filename is already a path (absolute or relative with directories)
+        fullFilePath = filename;
+      } else if (currentPath) {
+        // filename is just a name, combine with currentPath
+        fullFilePath = `${currentPath}/${filename}`;
+      } else {
+        fullFilePath = filename;
+      }
+      this.moduleResolver.setCurrentFilePath(fullFilePath);
+
+      // 3. Load builtins (auto-imported functions like sin, cos, etc.)
+      if (this.debug) console.log('[StoneEngine] Step 3a: Loading builtins...');
+      const builtinsExports = await this.loadBuiltins();
+      const combinedVariables = { ...builtinsExports, ...variables };
+      if (this.debug) {
+        console.log('[StoneEngine] Builtins loaded:', Object.keys(builtinsExports).length, 'exports');
+      }
+
+      // 3b. Load module dependencies
+      if (this.debug) console.log('[StoneEngine] Step 3b: Loading module dependencies...');
+      const hasImports = ast.imports && ast.imports.length > 0;
+      if (hasImports) {
+        await this.loadModuleDependencies(ast, fullFilePath);
+
+        // Execute imported modules
+        for (const importNode of ast.imports) {
+          const modulePath = importNode.modulePath;
+          if (this.debug) console.log('[StoneEngine] Processing import:', modulePath);
+          if (!this.moduleResolver.isBuiltinModule(modulePath)) {
+            if (this.debug) console.log('[StoneEngine] Executing module:', modulePath);
+            await this.executeModule(modulePath, { variables: combinedVariables });
+          } else {
+            if (this.debug) console.log('[StoneEngine] Skipping JS builtin:', modulePath);
+          }
+        }
+      }
+
+      // 4. Type check
+      if (this.debug) console.log('[StoneEngine] Step 4: Type checking...');
+      const typeResult = this.typeCheck(ast);
+      if (!typeResult.success) {
+        const errors = typeResult.errors.map(err => {
+          const loc = err.location
+            ? `[${err.location.line}:${err.location.column}] `
+            : '';
+          return `${loc}${err.message}`;
+        });
+
+        // Report type errors via adapter
+        for (const err of typeResult.errors) {
+          adapter.error(err.message, err.location);
+        }
+        adapter.finish(false, null);
+
+        return {
+          success: false,
+          error: 'Type check failed',
+          errors: typeResult.errors,
+          output: errors,
+          terminalsData: {},
+          duration: Date.now() - startTime,
+        };
+      }
+
+      // 5. Execute using bytecode VM (unified execution path)
+      if (this.debug) console.log('[StoneEngine] Step 5: Executing with VM...');
+      const result = await this.executeWithVM(ast, {
+        maxIterations,
+        outputAdapter: adapter,
+        externalVars: combinedVariables,
+        extensions: typeResult.extensions, // Pass extension info to compiler
+      });
+
+      if (this.debug) {
+        console.log('[StoneEngine] Execution complete:');
+        console.log('[StoneEngine]   success:', result.success);
+        console.log('[StoneEngine]   error:', result.error);
+        console.log('[StoneEngine]   output:', result.output?.length, 'lines');
+        console.log('[StoneEngine]   terminalsData keys:', Object.keys(result.terminalsData || {}));
+      }
+
+      return {
+        ...result,
+        duration: Date.now() - startTime,
+      };
+    } catch (error) {
+      // Report error via adapter
+      adapter.error(error.message, null);
+      adapter.finish(false, error);
+
+      // Include error in output and terminalsData for display
+      return {
+        success: false,
+        error: error.message,
+        output: [`Error: ${error.message}`],
+        terminalsData: {
+          main: {
+            type: 'console',
+            config: { title: 'Main', max_lines: 200 },
+            lines: [`Error: ${error.message}`],
+          }
+        },
+        duration: Date.now() - startTime,
+      };
+    }
+  }
+
+  /**
+   * Execute using bytecode VM
+   * @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 adapter = options.outputAdapter || this.outputAdapter;
+    const externalVars = options.externalVars || {};
+    const extensions = options.extensions || new Set();
+
+    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, passing extensions from type checking
+      const compiled = compiler.compile(ast, { extensions });
+
+      if (!compiled.success) {
+        const errorMsg = compiled.errors.map(e => e.message).join('\n');
+        if (adapter) {
+          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}`],
+            }
+          },
+        };
+      }
+
+      // Reset VM modules before loading (indices are relative to each execution)
+      this.vm.modules = [];
+      this.vm.moduleLocals = [];
+
+      // Load imported modules into VM before execution
+      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);
+            if (this.debug) {
+              console.log(`[executeWithVM] Builtin module '${modulePath}':`, Object.keys(moduleExports || {}));
+            }
+          } else {
+            const cachedModule = this.moduleResolver.cache.get(modulePath);
+            moduleExports = cachedModule?.exports;
+            if (this.debug) {
+              console.log(`[executeWithVM] Cached module '${modulePath}':`, Object.keys(moduleExports || {}));
+            }
+          }
+
+          if (!moduleExports) {
+            throw new Error(`Module '${modulePath}' not found or not loaded`);
+          }
+
+          // Create a module structure for the VM
+          const exportsMap = new Map();
+          const moduleIdx = this.vm.modules.length; // Index where this module will be stored
+
+          // Get cached module data
+          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] : [];
+
+          // Handle namespace imports (import math) vs selective imports (import x from math)
+          const isNamespaceImport = importedNames.length === 1 && importedNames[0] === '*';
+
+          if (isNamespaceImport) {
+            // For namespace imports, create an object with all exports
+            const namespaceObj = { ...moduleExports };
+            exportsMap.set('*', { slot: 0 });
+            moduleStorage[0] = namespaceObj;
+
+            // Tag any CompiledFunctions in the namespace
+            for (const value of Object.values(namespaceObj)) {
+              if (value instanceof CompiledFunction) {
+                this._tagFunctionWithModuleIdx(value, moduleIdx);
+              }
+            }
+          } else {
+            // Selective imports - original logic
+            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 vmResult = await this.vm.execute(compiled, {
+        outputAdapter: adapter,
+        externalVars
+      });
+
+      // Get output from adapter if it's a BufferedOutputAdapter, otherwise from VM
+      const outputFromAdapter = adapter?.output || [];
+      const terminalsFromAdapter = adapter?.terminalsData || {};
+      let combinedOutput = vmResult.output?.length > 0 ? vmResult.output : outputFromAdapter;
+
+      // If execution failed, add error to output
+      if (!vmResult.success && vmResult.error) {
+        combinedOutput = [...combinedOutput, `Error: ${vmResult.error}`];
+      }
+
+      // Build terminalsData - prefer adapter's data if available
+      let terminalsData = Object.keys(terminalsFromAdapter).length > 0
+        ? terminalsFromAdapter
+        : (combinedOutput.length > 0 ? {
+            main: {
+              type: 'console',
+              config: { title: 'Main', max_lines: 200 },
+              lines: combinedOutput,
+            }
+          } : {});
+
+      // Ensure errors are in terminalsData even if no other output
+      if (!vmResult.success && vmResult.error && Object.keys(terminalsData).length === 0) {
+        terminalsData = {
+          main: {
+            type: 'console',
+            config: { title: 'Main', max_lines: 200 },
+            lines: [`Error: ${vmResult.error}`],
+          }
+        };
+      }
+
+      // 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];
+      }
+
+      return {
+        success: vmResult.success,
+        result: vmResult.result,
+        output: combinedOutput,
+        error: vmResult.error,
+        variables: {},
+        terminalsData,
+        exports: vmResult.exports,  // Pass through exports from VM
+        exportSlots: vmResult.exportSlots,  // Original slot positions for exports
+        compiledExports: compiled.exports,  // Full export info including overload data
+        allLocals,  // All locals for module caching
+      };
+    } catch (e) {
+      if (adapter) {
+        adapter.error(e.message, null);
+        adapter.finish(false, e);
+      }
+      // Add error to terminalsData so it displays in viewport
+      const errorTerminalsData = {
+        main: {
+          type: 'console',
+          config: { title: 'Main', max_lines: 200 },
+          lines: [`Error: ${e.message}`],
+        }
+      };
+      return {
+        success: false,
+        error: e.message,
+        output: [`Error: ${e.message}`],
+        result: null,
+        terminalsData: errorTerminalsData,
+      };
+    }
+  }
+
+  /**
+   * Load module dependencies recursively
+   * @param {Object} ast - AST with imports
+   * @param {string} currentFilePath - Current file path
+   * @param {Set} visited - Visited modules (for cycle detection)
+   */
+  async loadModuleDependencies(ast, currentFilePath = null, visited = new Set()) {
+    if (currentFilePath) {
+      this.moduleResolver.setCurrentFilePath(currentFilePath);
+    }
+
+    // Collect all modules to load (with inferredFilename for directory inference)
+    const modulesToLoad = [];
+
+    for (const importNode of ast.imports || []) {
+      modulesToLoad.push({
+        modulePath: importNode.modulePath,
+        inferredFilename: importNode.inferredFilename || null
+      });
+    }
+
+    for (const exportNode of ast.exports || []) {
+      if (exportNode.type === 'SelectiveReExportStatement' ||
+          exportNode.type === 'NamespaceReExportStatement') {
+        modulesToLoad.push({
+          modulePath: exportNode.modulePath,
+          inferredFilename: null  // Re-exports don't use directory inference
+        });
+      }
+    }
+
+    // Load all modules
+    for (const { modulePath, inferredFilename } 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),
+        inferredFilename  // Pass inferredFilename for directory + inferred filename resolution
+      );
+
+      if (moduleData.ast && moduleData.fileId) {
+        await this.loadModuleDependencies(moduleData.ast, moduleData.fileId, visited);
+      }
+    }
+  }
+
+  /**
+   * Execute a module and cache its exports
+   * @param {string} modulePath - Module path
+   * @param {Object} options - Execution options
+   * @returns {Promise<Object>} Module exports
+   */
+  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}`);
+    }
+
+    // Load dependencies
+    await this.loadModuleDependencies(moduleData.ast, moduleData.fileId);
+
+    // 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);
+        }
+      }
+    }
+
+    // Type check module
+    const typeResult = this.typeCheck(moduleData.ast);
+    if (!typeResult.success) {
+      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, {
+      externalVars: options.variables || {},
+    });
+
+    if (!vmResult.success) {
+      throw new Error(`Error executing module '${modulePath}': ${vmResult.error}`);
+    }
+
+    const exports = vmResult.exports || {};
+
+    // Resolve re-exports to actual values
+    await this.resolveReExports(exports, modulePath);
+
+    moduleData.exports = exports;
+    // Cache all locals for closure upvalue capture when module is imported
+    moduleData.allLocals = vmResult.allLocals || [];
+    // Cache original export slots for correct IMPORT_GET resolution
+    moduleData.exportSlots = vmResult.exportSlots || {};
+    // Cache full export info for overloaded functions
+    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) {
+    // Arithmetic operations with two Complex arguments
+    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' } },
+    ];
+
+    // Unary operations
+    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 {
+        // Try to get from compiledExports which has slot info
+        const exportInfo = compiledExports.get(name);
+        if (exportInfo && allLocals[exportInfo.slot] instanceof CompiledFunction) {
+          registerOverload(name, allLocals[exportInfo.slot], sig);
+        }
+      }
+    }
+  }
+
+  /**
+   * Clear the module cache
+   */
+  clearModuleCache() {
+    this.moduleResolver.clearCache();
+  }
+
+  /**
+   * 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) {
+    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
+        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 });
+        }
+      }
+    }
+  }
+
+  /**
+   * Load builtins.stn exports (auto-imported primitives)
+   */
+  async loadBuiltins() {
+    if (this.stnBuiltinsExports) {
+      return this.stnBuiltinsExports;
+    }
+
+    try {
+      await this.moduleResolver.loadModule(
+        'builtins',
+        (source, opts) => this.parse(source, opts)
+      );
+
+      const exports = await this.executeModule('builtins', {});
+      this.stnBuiltinsExports = exports || {};
+
+      if (this.debug) {
+        console.log('Loaded builtins.stn exports:', Object.keys(this.stnBuiltinsExports));
+      }
+
+      return this.stnBuiltinsExports;
+    } catch (error) {
+      if (this.debug) {
+        console.error('Failed to load builtins.stn:', error);
+      }
+      return {};
+    }
+  }
+}
+
+export default StoneEngine;