@ball-lang/engine 0.2.1 → 1.3.5

package/dist/index.js

@@ -1,962 +1,99 @@
 /**
  * Ball TypeScript Engine — interprets Ball programs directly from JSON.
  *
- * Runs in Node.js and browsers. No protobuf dependency — works with
- * proto3 JSON representation of Ball programs.
+ * This is a compatibility wrapper around the compiled (self-hosted)
+ * Ball engine.  The compiled engine is generated by compiling
+ * `dart/self_host/engine.ball.json` through `@ball-lang/compiler`.
  *
  * Usage:
  *   import { BallEngine } from '@ball-lang/engine';
- *   const engine = new BallEngine(programJson, { stdout: console.log });
- *   engine.run();
+ *   const engine = new BallEngine(programJson);
+ *   await engine.run();
+ *   console.log(engine.getOutput());
  */
-// ── Flow signals ────────────────────────────────────────────────────────────
-class FlowSignal {
-    kind;
-    value;
-    label;
-    constructor(kind, value, label) {
-        this.kind = kind;
-        this.value = value;
-        this.label = label;
-    }
-}
-class BallException {
-    typeName;
-    value;
-    constructor(typeName, value) {
-        this.typeName = typeName;
-        this.value = value;
-    }
-}
-class BallRuntimeError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'BallRuntimeError';
-    }
-}
-// ── Scope ───────────────────────────────────────────────────────────────────
-class Scope {
-    bindings = new Map();
-    parent;
-    constructor(parent) {
-        this.parent = parent;
-    }
-    bind(name, value) {
-        this.bindings.set(name, value);
-    }
-    has(name) {
-        return this.bindings.has(name) || (this.parent?.has(name) ?? false);
-    }
-    lookup(name) {
-        if (this.bindings.has(name))
-            return this.bindings.get(name);
-        if (this.parent)
-            return this.parent.lookup(name);
-        throw new BallRuntimeError(`Undefined variable: "${name}"`);
-    }
-    assign(name, value) {
-        if (this.bindings.has(name)) {
-            this.bindings.set(name, value);
-            return;
-        }
-        if (this.parent) {
-            this.parent.assign(name, value);
-            return;
-        }
-        throw new BallRuntimeError(`Cannot assign to undefined variable: "${name}"`);
-    }
-    child() {
-        return new Scope(this);
-    }
-}
+import { BallEngine as CompiledEngine, } from "./compiled_engine.js";
+import * as _compiled from "./compiled_engine.js";
+import { createEngineSetup } from "./engine_setup.js";
+import { unwrapBallFile } from "./ball_file.js";
+// All proto3-JSON normalization, the method-dispatch handler, the extra
+// std-function registrations, and the compiled-engine patches live in the
+// shared `engine_setup` module so the Phase 2.7b conformance harness (which
+// runs against a freshly compiled engine) can reuse the exact same setup.
+const _setup = createEngineSetup(_compiled);
+const protoWrap = _setup.protoWrap;
+const MethodDispatchHandler = _setup.MethodDispatchHandler;
+const StdModuleHandler = _compiled.StdModuleHandler;
+const registerExtraStdFunctions = _setup.registerExtraStdFunctions;
+const seedGlobalScope = _setup.seedGlobalScope;
+const patchCompiledEngine = _setup.patchCompiledEngine;
+const patchScopeBindings = _setup.patchScopeBindings;
 export class BallEngine {
-    program;
-    stdout;
-    stderr;
-    functions = new Map();
-    constructors = new Map();
-    enumValues = new Map();
-    currentModule = '';
-    activeException = null;
-    output = [];
+    _compiledEngine;
+    _output = [];
     constructor(program, options = {}) {
-        this.program = typeof program === 'string' ? JSON.parse(program) : program;
-        this.stdout = options.stdout ?? ((msg) => this.output.push(msg));
-        this.stderr = options.stderr ?? (() => { });
-        this.buildLookupTables();
-    }
-    buildLookupTables() {
-        for (const mod of this.program.modules) {
-            // Index enum types from module (if present).
-            const enums = mod.enums;
-            if (Array.isArray(enums)) {
-                for (const enumDesc of enums) {
-                    const enumName = enumDesc.name; // e.g. "main:Color"
-                    const values = {};
-                    for (const v of (enumDesc.value ?? enumDesc.values ?? [])) {
-                        values[v.name] = { __type__: enumName, name: v.name, index: v.number ?? v.index ?? 0 };
-                    }
-                    this.enumValues.set(enumName, values);
-                    const ec = enumName.indexOf(':');
-                    if (ec >= 0)
-                        this.enumValues.set(enumName.substring(ec + 1), values);
-                }
-            }
-            for (const fn of mod.functions) {
-                this.functions.set(`${mod.name}.${fn.name}`, fn);
-                // Register constructors (metadata.kind === "constructor").
-                const kind = fn.metadata?.kind;
-                if (kind === 'constructor') {
-                    const entry = { module: mod.name, fn };
-                    // fn.name is "ClassName.new" or "ClassName.named".
-                    const dotIdx = fn.name.indexOf('.');
-                    if (dotIdx >= 0) {
-                        const className = fn.name.substring(0, dotIdx);
-                        const ctorSuffix = fn.name.substring(dotIdx + 1);
-                        if (ctorSuffix === 'new') {
-                            this.constructors.set(className, entry);
-                            this.constructors.set(`${mod.name}:${className}`, entry);
-                        }
-                        this.constructors.set(fn.name, entry);
-                    }
-                }
-            }
-        }
-    }
-    run() {
-        const key = `${this.program.entryModule}.${this.program.entryFunction}`;
-        const fn = this.functions.get(key);
-        if (!fn)
-            throw new BallRuntimeError(`Entry function "${key}" not found`);
-        const scope = new Scope();
-        this.currentModule = this.program.entryModule;
-        const result = this.callFunction(this.program.entryModule, fn, null, scope);
-        if (result instanceof FlowSignal && result.kind === 'return') {
-            return this.output;
-        }
-        return this.output;
-    }
+        // Ball files are self-describing `google.protobuf.Any` envelopes. Unwrap
+        // the `@type` envelope (if present) before normalizing; callers passing an
+        // already-unwrapped Program object are still supported.
+        const parsed = typeof program === 'string' ? JSON.parse(program) : program;
+        const normalized = protoWrap(unwrapBallFile(parsed));
+        const stdHandler = new StdModuleHandler();
+        const methodHandler = new MethodDispatchHandler();
+        const outputCapture = this._output;
+        const stdoutFn = options.stdout ?? ((msg) => {
+            outputCapture.push(msg);
+        });
+        const stderrFn = options.stderr ?? (() => { });
+        // The self-hosted engine constructor takes 16 positional parameters:
+        //   program, stdout, stderr, stdinReader, envGet, args, enableProfiling,
+        //   maxRecursionDepth, timeoutMs, maxMemoryBytes, maxModules,
+        //   maxExpressionDepth, maxProgramSizeBytes, sandbox, moduleHandlers,
+        //   resolver
+        // (older IR revisions only had 9). Options default to permissive values
+        // unless the caller explicitly sets them.
+        this._compiledEngine = new CompiledEngine(normalized, stdoutFn, stderrFn, null, // stdinReader
+        null, // envGet
+        [], // args
+        false, // enableProfiling
+        options.maxRecursionDepth ?? 100000, // maxRecursionDepth
+        options.timeoutMs ?? null, // timeoutMs (null = unbounded)
+        options.maxMemoryBytes ?? null, // maxMemoryBytes (null = unbounded)
+        options.maxModules ?? 1000000, // maxModules
+        options.maxExpressionDepth ?? 1000000, // maxExpressionDepth
+        options.maxProgramSizeBytes ?? null, // maxProgramSizeBytes (null = skip)
+        options.sandbox ?? false, // sandbox
+        [methodHandler, stdHandler], // moduleHandlers
+        null);
+        // Patch scope bindings to use null-prototype objects (avoids
+        // Object.prototype.values/entries/keys getters polluting `in` checks).
+        if (typeof globalThis._patchScopeBindings === 'function') {
+            globalThis._patchScopeBindings(this._compiledEngine._globalScope);
+        }
+        else {
+            patchScopeBindings(this._compiledEngine._globalScope);
+        }
+        registerExtraStdFunctions(stdHandler);
+        seedGlobalScope(this._compiledEngine);
+        patchCompiledEngine(this._compiledEngine);
+        // Note: double formatting (12 vs 12.0) handled by BallDouble in preamble.
+        // The compiled engine returns raw numbers for literals; BallDouble wrapping
+        // happens in arithmetic operations (_stdAdd, _stdBinary, etc.).
+    }
+    /**
+     * Run the program.  Returns a promise that resolves to the captured
+     * output lines (same content as `getOutput()`).
+     *
+     * NOTE: The compiled engine is async internally.  If you were relying
+     * on synchronous `run()`, wrap your call in `await`.
+     */
+    async run() {
+        await this._compiledEngine.run();
+        return this._output;
+    }
+    /** Retrieve lines printed via `std.print` (when no custom stdout was given). */
     getOutput() {
-        return this.output;
-    }
-    // ── Expression evaluation ─────────────────────────────────────────────
-    evalExpr(expr, scope) {
-        if (expr.call)
-            return this.evalCall(expr.call, scope);
-        if (expr.literal)
-            return this.evalLiteral(expr.literal, scope);
-        if (expr.reference)
-            return this.evalReference(expr.reference, scope);
-        if (expr.fieldAccess)
-            return this.evalFieldAccess(expr.fieldAccess, scope);
-        if (expr.messageCreation)
-            return this.evalMessageCreation(expr.messageCreation, scope);
-        if (expr.block)
-            return this.evalBlock(expr.block, scope);
-        if (expr.lambda)
-            return this.evalLambda(expr.lambda, scope);
-        return null;
-    }
-    evalCall(call, scope) {
-        const moduleName = call.module || this.currentModule;
-        // Lazy control flow
-        if (moduleName === 'std' || moduleName === 'dart_std') {
-            switch (call.function) {
-                case 'if': return this.evalLazyIf(call, scope);
-                case 'for': return this.evalLazyFor(call, scope);
-                case 'for_in': return this.evalLazyForIn(call, scope);
-                case 'while': return this.evalLazyWhile(call, scope);
-                case 'do_while': return this.evalLazyDoWhile(call, scope);
-                case 'switch': return this.evalLazySwitch(call, scope);
-                case 'try': return this.evalLazyTry(call, scope);
-                case 'and': return this.evalShortCircuitAnd(call, scope);
-                case 'or': return this.evalShortCircuitOr(call, scope);
-                case 'return': return this.evalReturn(call, scope);
-                case 'break': return new FlowSignal('break', undefined, this.lazyStringField(call, 'label'));
-                case 'continue': return new FlowSignal('continue', undefined, this.lazyStringField(call, 'label'));
-                case 'assign': return this.evalAssign(call, scope);
-                case 'labeled': return this.evalLabeled(call, scope);
-                case 'pre_increment':
-                case 'post_increment':
-                case 'pre_decrement':
-                case 'post_decrement':
-                    return this.evalIncDec(call, scope);
-            }
-        }
-        // Eager evaluation
-        const input = call.input ? this.evalExpr(call.input, scope) : null;
-        // Fast path for explicit std calls
-        if (call.module === 'std' || call.module === 'dart_std') {
-            return this.callBaseFunction(call.module, call.function, input);
-        }
-        // Method call on object (has 'self' field) — instance method dispatch.
-        if (input && typeof input === 'object' && !Array.isArray(input) && 'self' in input) {
-            const self = input.self;
-            if (self && typeof self === 'object' && !Array.isArray(self)) {
-                const typeName = self.__type__;
-                if (typeName) {
-                    const colonIdx = typeName.indexOf(':');
-                    const modPart = colonIdx >= 0 ? typeName.substring(0, colonIdx) : this.currentModule;
-                    // Try ClassName.methodName
-                    const methodKey = `${modPart}.${typeName}.${call.function}`;
-                    const method = this.functions.get(methodKey);
-                    if (method)
-                        return this.callFunction(modPart, method, input, scope);
-                    // Walk __super__ chain for inherited methods.
-                    let superObj = self.__super__;
-                    while (superObj && typeof superObj === 'object' && !Array.isArray(superObj)) {
-                        const superType = superObj.__type__;
-                        if (superType) {
-                            const sColonIdx = superType.indexOf(':');
-                            const sModPart = sColonIdx >= 0 ? superType.substring(0, sColonIdx) : modPart;
-                            const sTypeName = sColonIdx >= 0 ? superType : `${sModPart}:${superType}`;
-                            const superMethodKey = `${sModPart}.${sTypeName}.${call.function}`;
-                            const superMethod = this.functions.get(superMethodKey);
-                            if (superMethod)
-                                return this.callFunction(sModPart, superMethod, input, scope);
-                        }
-                        superObj = superObj.__super__;
-                    }
-                }
-            }
-            // Fall through to normal resolution if no method found on the type.
-        }
-        const key = `${moduleName}.${call.function}`;
-        const fn = this.functions.get(key);
-        if (fn?.isBase)
-            return this.callBaseFunction(moduleName, call.function, input);
-        // Scope closure lookup
-        if (!call.module && scope.has(call.function)) {
-            const bound = scope.lookup(call.function);
-            if (typeof bound === 'function')
-                return bound(input);
-        }
-        // Module function lookup
-        if (fn)
-            return this.callFunction(moduleName, fn, input, scope);
-        // Fallback: scan all modules
-        for (const mod of this.program.modules) {
-            for (const f of mod.functions) {
-                if (f.name === call.function) {
-                    return this.callFunction(mod.name, f, input, scope);
-                }
-            }
-        }
-        throw new BallRuntimeError(`Function "${key}" not found`);
-    }
-    callFunction(moduleName, fn, input, parentScope) {
-        if (fn.isBase)
-            return this.callBaseFunction(moduleName, fn.name, input);
-        if (!fn.body)
-            return null;
-        const prevModule = this.currentModule;
-        this.currentModule = moduleName;
-        const fnScope = parentScope.child();
-        fnScope.bind('input', input);
-        // Bind 'self' for instance method calls so `this` references resolve.
-        if (input && typeof input === 'object' && !Array.isArray(input) && 'self' in input) {
-            fnScope.bind('self', input.self);
-        }
-        // Destructure input fields as named parameters
-        const params = fn.metadata?.params;
-        if (params && Array.isArray(params)) {
-            if (params.length === 1 && (input === null || input === undefined || typeof input !== 'object' || Array.isArray(input))) {
-                // Single-param function with non-object input: bind directly
-                const name = typeof params[0] === 'string' ? params[0] : params[0].name;
-                if (name)
-                    fnScope.bind(name, input);
-            }
-            else if (input && typeof input === 'object' && !Array.isArray(input)) {
-                for (let i = 0; i < params.length; i++) {
-                    const p = params[i];
-                    const name = typeof p === 'string' ? p : p.name;
-                    if (!name)
-                        continue;
-                    if (name in input) {
-                        fnScope.bind(name, input[name]);
-                    }
-                    else if (`arg${i}` in input) {
-                        fnScope.bind(name, input[`arg${i}`]);
-                    }
-                }
-            }
-        }
-        let result = this.evalExpr(fn.body, fnScope);
-        this.currentModule = prevModule;
-        if (result instanceof FlowSignal && result.kind === 'return') {
-            return result.value;
-        }
-        return result;
-    }
-    // ── Literals ──────────────────────────────────────────────────────────
-    evalLiteral(lit, scope) {
-        if (lit.intValue !== undefined)
-            return typeof lit.intValue === 'string' ? parseInt(lit.intValue) : lit.intValue;
-        if (lit.doubleValue !== undefined)
-            return lit.doubleValue;
-        if (lit.stringValue !== undefined)
-            return lit.stringValue;
-        if (lit.boolValue !== undefined)
-            return lit.boolValue;
-        if (lit.listValue)
-            return lit.listValue.elements.map(e => this.evalExpr(e, scope));
-        return null;
-    }
-    evalReference(ref, scope) {
-        const name = ref.name;
-        if (scope.has(name))
-            return scope.lookup(name);
-        // Constructor tear-off: resolve class names to callable closures.
-        const ctorEntry = this.constructors.get(name);
-        if (ctorEntry) {
-            return (input) => this.callFunction(ctorEntry.module, ctorEntry.fn, input, scope);
-        }
-        // Try stripping module prefix (e.g. "main:Foo" -> "Foo").
-        const colonIdx = name.indexOf(':');
-        if (colonIdx >= 0) {
-            const bare = name.substring(colonIdx + 1);
-            const bareEntry = this.constructors.get(bare);
-            if (bareEntry) {
-                return (input) => this.callFunction(bareEntry.module, bareEntry.fn, input, scope);
-            }
-        }
-        // Enum type reference: resolve to a map of enum values.
-        const enumVals = this.enumValues.get(name);
-        if (enumVals)
-            return enumVals;
-        return scope.lookup(name);
-    }
-    evalFieldAccess(fa, scope) {
-        const obj = this.evalExpr(fa.object, scope);
-        // Handle string properties
-        if (typeof obj === 'string') {
-            if (fa.field === 'length')
-                return obj.length;
-            return null;
-        }
-        // Handle array properties
-        if (Array.isArray(obj)) {
-            if (fa.field === 'length')
-                return obj.length;
-            return null;
-        }
-        if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
-            if (fa.field in obj)
-                return obj[fa.field];
-            // Walk __super__ chain for inherited fields.
-            let superObj = obj.__super__;
-            while (superObj && typeof superObj === 'object' && !Array.isArray(superObj)) {
-                if (fa.field in superObj)
-                    return superObj[fa.field];
-                superObj = superObj.__super__;
-            }
-        }
-        return null;
-    }
-    evalMessageCreation(mc, scope) {
-        const result = {};
-        for (const f of mc.fields) {
-            result[f.name] = this.evalExpr(f.value, scope);
-        }
-        return result;
-    }
-    evalBlock(block, scope) {
-        const blockScope = scope.child();
-        let lastResult = null;
-        for (const stmt of block.statements) {
-            if (stmt.let) {
-                const val = this.evalExpr(stmt.let.value, blockScope);
-                if (val instanceof FlowSignal)
-                    return val;
-                blockScope.bind(stmt.let.name, val);
-            }
-            if (stmt.expression) {
-                lastResult = this.evalExpr(stmt.expression, blockScope);
-                if (lastResult instanceof FlowSignal)
-                    return lastResult;
-            }
-        }
-        if (block.result) {
-            lastResult = this.evalExpr(block.result, blockScope);
-        }
-        return lastResult;
-    }
-    evalLambda(lambda, scope) {
-        return (input) => {
-            const lambdaScope = scope.child();
-            lambdaScope.bind('input', input);
-            const params = lambda.metadata?.params;
-            if (params && Array.isArray(params)) {
-                if (params.length === 1 && (input === null || input === undefined || typeof input !== 'object' || Array.isArray(input))) {
-                    const name = typeof params[0] === 'string' ? params[0] : params[0].name;
-                    if (name)
-                        lambdaScope.bind(name, input);
-                }
-                else if (input && typeof input === 'object' && !Array.isArray(input)) {
-                    for (let i = 0; i < params.length; i++) {
-                        const p = params[i];
-                        const name = typeof p === 'string' ? p : p.name;
-                        if (!name)
-                            continue;
-                        if (name in input) {
-                            lambdaScope.bind(name, input[name]);
-                        }
-                        else if (`arg${i}` in input) {
-                            lambdaScope.bind(name, input[`arg${i}`]);
-                        }
-                    }
-                }
-            }
-            const result = this.evalExpr(lambda.body, lambdaScope);
-            if (result instanceof FlowSignal && result.kind === 'return')
-                return result.value;
-            return result;
-        };
-    }
-    // ── Lazy control flow ─────────────────────────────────────────────────
-    lazyFields(call) {
-        if (!call.input?.messageCreation)
-            return {};
-        const result = {};
-        for (const f of call.input.messageCreation.fields) {
-            result[f.name] = f.value;
-        }
-        return result;
-    }
-    lazyStringField(call, name) {
-        const fields = this.lazyFields(call);
-        const expr = fields[name];
-        if (!expr?.literal?.stringValue)
-            return undefined;
-        return expr.literal.stringValue;
-    }
-    evalLazyIf(call, scope) {
-        const fields = this.lazyFields(call);
-        if (!fields.condition)
-            return null;
-        const cond = this.evalExpr(fields.condition, scope);
-        if (this.toBool(cond)) {
-            return fields.then ? this.evalExpr(fields.then, scope) : null;
-        }
-        return fields.else ? this.evalExpr(fields.else, scope) : null;
-    }
-    evalLazyWhile(call, scope) {
-        const fields = this.lazyFields(call);
-        while (true) {
-            if (fields.condition) {
-                if (!this.toBool(this.evalExpr(fields.condition, scope)))
-                    break;
-            }
-            if (fields.body) {
-                const result = this.evalExpr(fields.body, scope);
-                if (result instanceof FlowSignal) {
-                    if (result.kind === 'return')
-                        return result;
-                    if (result.label)
-                        return result;
-                    if (result.kind === 'break')
-                        break;
-                    if (result.kind === 'continue')
-                        continue;
-                }
-            }
-        }
-        return null;
-    }
-    evalLazyDoWhile(call, scope) {
-        const fields = this.lazyFields(call);
-        do {
-            if (fields.body) {
-                const result = this.evalExpr(fields.body, scope);
-                if (result instanceof FlowSignal) {
-                    if (result.kind === 'return')
-                        return result;
-                    if (result.kind === 'break')
-                        break;
-                }
-            }
-            if (fields.condition) {
-                if (!this.toBool(this.evalExpr(fields.condition, scope)))
-                    break;
-            }
-            else
-                break;
-        } while (true);
-        return null;
-    }
-    evalLazyFor(call, scope) {
-        const fields = this.lazyFields(call);
-        const forScope = scope.child();
-        if (fields.init) {
-            // Handle init as string literal "var i = 0" (encoder format)
-            if (fields.init.literal?.stringValue) {
-                const match = fields.init.literal.stringValue.match(/^(?:var|final|int|double|String)\s+(\w+)\s*=\s*(.+)$/);
-                if (match) {
-                    const varName = match[1];
-                    const rawVal = match[2].trim();
-                    const parsed = rawVal === 'true' ? true : rawVal === 'false' ? false : (isNaN(Number(rawVal)) ? rawVal : Number(rawVal));
-                    forScope.bind(varName, parsed);
-                }
-            }
-            else if (fields.init.block) {
-                this.evalBlock(fields.init.block, forScope);
-            }
-            else {
-                this.evalExpr(fields.init, forScope);
-            }
-        }
-        while (true) {
-            if (fields.condition) {
-                if (!this.toBool(this.evalExpr(fields.condition, forScope)))
-                    break;
-            }
-            if (fields.body) {
-                const result = this.evalExpr(fields.body, forScope);
-                if (result instanceof FlowSignal) {
-                    if (result.kind === 'return')
-                        return result;
-                    if (result.label)
-                        return result;
-                    if (result.kind === 'break')
-                        break;
-                    if (result.kind === 'continue') {
-                        if (fields.update)
-                            this.evalExpr(fields.update, forScope);
-                        continue;
-                    }
-                }
-            }
-            if (fields.update)
-                this.evalExpr(fields.update, forScope);
-        }
-        return null;
-    }
-    evalLazyForIn(call, scope) {
-        const fields = this.lazyFields(call);
-        const varName = fields.variable?.literal?.stringValue ?? 'item';
-        if (!fields.iterable || !fields.body)
-            return null;
-        const iterable = this.evalExpr(fields.iterable, scope);
-        if (!Array.isArray(iterable))
-            throw new BallRuntimeError('for_in: iterable is not a List');
-        for (const item of iterable) {
-            const loopScope = scope.child();
-            loopScope.bind(varName, item);
-            const result = this.evalExpr(fields.body, loopScope);
-            if (result instanceof FlowSignal) {
-                if (result.kind === 'return')
-                    return result;
-                if (result.label)
-                    return result;
-                if (result.kind === 'break')
-                    break;
-                if (result.kind === 'continue')
-                    continue;
-            }
-        }
-        return null;
-    }
-    evalLazySwitch(call, scope) {
-        const fields = this.lazyFields(call);
-        if (!fields.subject || !fields.cases)
-            return null;
-        const subject = this.evalExpr(fields.subject, scope);
-        const cases = fields.cases.literal?.listValue?.elements ?? [];
-        let defaultBody;
-        for (const c of cases) {
-            if (!c.messageCreation)
-                continue;
-            const cf = {};
-            for (const f of c.messageCreation.fields)
-                cf[f.name] = f.value;
-            if (cf.is_default?.literal?.boolValue) {
-                defaultBody = cf.body;
-                continue;
-            }
-            if (cf.value) {
-                const caseVal = this.evalExpr(cf.value, scope);
-                if (caseVal === subject && cf.body)
-                    return this.evalExpr(cf.body, scope);
-            }
-        }
-        if (defaultBody)
-            return this.evalExpr(defaultBody, scope);
-        return null;
-    }
-    evalLazyTry(call, scope) {
-        const fields = this.lazyFields(call);
-        let result = null;
-        try {
-            result = fields.body ? this.evalExpr(fields.body, scope) : null;
-        }
-        catch (e) {
-            result = null;
-            const catches = fields.catches?.literal?.listValue?.elements ?? [];
-            let caught = false;
-            for (const c of catches) {
-                if (!c.messageCreation)
-                    continue;
-                const cf = {};
-                for (const f of c.messageCreation.fields)
-                    cf[f.name] = f.value;
-                const catchType = cf.type?.literal?.stringValue;
-                if (catchType) {
-                    const matches = e instanceof BallException ? e.typeName === catchType : e.constructor?.name === catchType;
-                    if (!matches)
-                        continue;
-                }
-                const variable = cf.variable?.literal?.stringValue ?? 'e';
-                if (cf.body) {
-                    const catchScope = scope.child();
-                    catchScope.bind(variable, e instanceof BallException ? e.value : (e instanceof Error ? e.message : String(e)));
-                    const prev = this.activeException;
-                    this.activeException = e;
-                    try {
-                        result = this.evalExpr(cf.body, catchScope);
-                    }
-                    finally {
-                        this.activeException = prev;
-                    }
-                    caught = true;
-                    break;
-                }
-            }
-            if (!caught)
-                throw e;
-        }
-        finally {
-            if (fields.finally)
-                this.evalExpr(fields.finally, scope);
-        }
-        return result;
-    }
-    evalShortCircuitAnd(call, scope) {
-        const fields = this.lazyFields(call);
-        if (!fields.left || !fields.right)
-            return false;
-        if (!this.toBool(this.evalExpr(fields.left, scope)))
-            return false;
-        return this.toBool(this.evalExpr(fields.right, scope));
-    }
-    evalShortCircuitOr(call, scope) {
-        const fields = this.lazyFields(call);
-        if (!fields.left || !fields.right)
-            return false;
-        if (this.toBool(this.evalExpr(fields.left, scope)))
-            return true;
-        return this.toBool(this.evalExpr(fields.right, scope));
-    }
-    evalReturn(call, scope) {
-        const fields = this.lazyFields(call);
-        const val = fields.value ? this.evalExpr(fields.value, scope) : null;
-        return new FlowSignal('return', val);
-    }
-    evalAssign(call, scope) {
-        const fields = this.lazyFields(call);
-        if (!fields.value)
-            return null;
-        const val = this.evalExpr(fields.value, scope);
-        // Target can be a reference expression or a string literal name.
-        const target = fields.target ?? fields.name ?? fields.variable;
-        if (!target)
-            return null;
-        let name;
-        if (target.reference) {
-            name = target.reference.name;
-        }
-        else if (target.literal?.stringValue) {
-            name = target.literal.stringValue;
-        }
-        if (!name)
-            return null;
-        const op = fields.op?.literal?.stringValue;
-        if (op && op !== '=') {
-            const current = scope.lookup(name);
-            const computed = this.applyCompoundOp(op, current, val);
-            try {
-                scope.assign(name, computed);
-            }
-            catch {
-                scope.bind(name, computed);
-            }
-            return computed;
-        }
-        try {
-            scope.assign(name, val);
-        }
-        catch {
-            scope.bind(name, val);
-        }
-        return val;
-    }
-    applyCompoundOp(op, current, val) {
-        const a = this.toNum(current);
-        const b = this.toNum(val);
-        switch (op) {
-            case '+=': return a + b;
-            case '-=': return a - b;
-            case '*=': return a * b;
-            case '/=': return Math.trunc(a / b);
-            case '%=': return a % b;
-            case '&=': return (a | 0) & (b | 0);
-            case '|=': return (a | 0) | (b | 0);
-            case '^=': return (a | 0) ^ (b | 0);
-            case '<<=': return (a | 0) << (b | 0);
-            case '>>=': return (a | 0) >> (b | 0);
-            default: return val;
-        }
-    }
-    evalIncDec(call, scope) {
-        const fields = this.lazyFields(call);
-        const valueExpr = fields.value;
-        if (!valueExpr)
-            return null;
-        if (valueExpr.reference) {
-            const name = valueExpr.reference.name;
-            const current = this.toNum(scope.lookup(name));
-            const isInc = call.function.includes('increment');
-            const isPre = call.function.startsWith('pre');
-            const updated = isInc ? current + 1 : current - 1;
-            scope.assign(name, updated);
-            return isPre ? updated : current;
-        }
-        // Fallback: just compute
-        const val = this.toNum(this.evalExpr(valueExpr, scope));
-        const isInc = call.function.includes('increment');
-        return isInc ? val + 1 : val - 1;
-    }
-    evalLabeled(call, scope) {
-        const fields = this.lazyFields(call);
-        const label = fields.label?.literal?.stringValue;
-        if (!fields.body)
-            return null;
-        const result = this.evalExpr(fields.body, scope);
-        if (result instanceof FlowSignal && result.label === label) {
-            if (result.kind === 'break')
-                return null;
-        }
-        return result;
-    }
-    // ── Base function dispatch ────────────────────────────────────────────
-    callBaseFunction(module, fn, input) {
-        const left = input?.left;
-        const right = input?.right;
-        const value = input?.value;
-        switch (fn) {
-            // I/O
-            case 'print':
-                this.stdout(this.ballToString(value ?? input?.message ?? input));
-                return null;
-            // Arithmetic
-            case 'add': {
-                if (typeof left === 'string' || typeof right === 'string')
-                    return String(left ?? '') + String(right ?? '');
-                return this.numOp(left, right, (a, b) => a + b);
-            }
-            case 'subtract': return this.numOp(left, right, (a, b) => a - b);
-            case 'multiply': return this.numOp(left, right, (a, b) => a * b);
-            case 'divide': return Math.trunc(this.toNum(left) / this.toNum(right));
-            case 'divide_double': return this.toNum(left) / this.toNum(right);
-            case 'modulo': return this.numOp(left, right, (a, b) => a % b);
-            case 'negate': return -this.toNum(value ?? input);
-            // Comparison
-            case 'equals': return left === right;
-            case 'not_equals': return left !== right;
-            case 'less_than': return this.toNum(left) < this.toNum(right);
-            case 'greater_than': return this.toNum(left) > this.toNum(right);
-            case 'lte': return this.toNum(left) <= this.toNum(right);
-            case 'gte': return this.toNum(left) >= this.toNum(right);
-            // Logical
-            case 'not': return !this.toBool(value ?? input);
-            // String
-            case 'concat': return String(left ?? '') + String(right ?? '');
-            case 'to_string': return this.ballToString(value ?? input);
-            case 'string_length': return String(value ?? input).length;
-            case 'string_contains': return String(input?.string ?? '').includes(String(input?.substring ?? ''));
-            case 'string_substring': return String(input?.string ?? '').substring(input?.start ?? 0, input?.end);
-            case 'string_to_upper': return String(value ?? input).toUpperCase();
-            case 'string_to_lower': return String(value ?? input).toLowerCase();
-            case 'string_trim': return String(value ?? input).trim();
-            case 'string_split': return String(input?.string ?? '').split(String(input?.delimiter ?? ''));
-            case 'string_replace': return String(input?.string ?? '').replace(String(input?.from ?? ''), String(input?.to ?? ''));
-            case 'string_replace_all': return String(input?.string ?? '').replaceAll(String(input?.from ?? ''), String(input?.to ?? ''));
-            case 'string_starts_with': return String(input?.string ?? '').startsWith(String(input?.prefix ?? ''));
-            case 'string_ends_with': return String(input?.string ?? '').endsWith(String(input?.suffix ?? ''));
-            case 'string_index_of': return String(input?.string ?? '').indexOf(String(input?.substring ?? ''));
-            // Type ops
-            case 'is': return this.typeMatches(input?.value, input?.type);
-            case 'is_not': return !this.typeMatches(input?.value, input?.type);
-            case 'as': return input?.value;
-            // Math
-            case 'math_abs': return Math.abs(this.toNum(value ?? input));
-            case 'math_floor': return Math.floor(this.toNum(value ?? input));
-            case 'math_ceil': return Math.ceil(this.toNum(value ?? input));
-            case 'math_round': return Math.round(this.toNum(value ?? input));
-            case 'math_sqrt': return Math.sqrt(this.toNum(value ?? input));
-            case 'math_pow': return Math.pow(this.toNum(input?.base ?? left), this.toNum(input?.exponent ?? right));
-            case 'math_min': return Math.min(this.toNum(left), this.toNum(right));
-            case 'math_max': return Math.max(this.toNum(left), this.toNum(right));
-            case 'math_pi': return Math.PI;
-            // Error handling
-            case 'throw': {
-                const rawVal = input?.value ?? input?.message ?? input;
-                const typeName = input?.type ?? rawVal?.__type ?? 'Exception';
-                throw new BallException(typeName, rawVal);
-            }
-            case 'rethrow': {
-                if (this.activeException)
-                    throw this.activeException;
-                throw new BallRuntimeError('rethrow outside of catch');
-            }
-            case 'assert': {
-                if (!this.toBool(input?.condition ?? input)) {
-                    throw new BallRuntimeError(`Assertion failed: ${input?.message ?? ''}`);
-                }
-                return null;
-            }
-            // Collections
-            case 'list_push': {
-                const l = [...(input?.list ?? [])];
-                l.push(input?.value);
-                return l;
-            }
-            case 'list_length': return (input?.list ?? input ?? []).length;
-            case 'list_get': return (input?.list ?? [])[input?.index ?? 0];
-            case 'list_map': {
-                const list = input?.list ?? [];
-                const fn = input?.function;
-                if (typeof fn === 'function')
-                    return list.map((item) => fn(item));
-                return list;
-            }
-            case 'list_filter': {
-                const list = input?.list ?? [];
-                const fn = input?.function;
-                if (typeof fn === 'function')
-                    return list.filter((item) => fn(item));
-                return list;
-            }
-            case 'map_get': return (input?.map ?? {})[input?.key];
-            case 'map_set': {
-                const m = { ...(input?.map ?? {}) };
-                m[input?.key] = input?.value;
-                return m;
-            }
-            case 'map_keys': return Object.keys(input?.map ?? input ?? {});
-            // Increment/decrement (pure value ops)
-            case 'pre_increment':
-            case 'post_increment': return this.toNum(value ?? input) + 1;
-            case 'pre_decrement':
-            case 'post_decrement': return this.toNum(value ?? input) - 1;
-            // Index
-            case 'index': {
-                const target = input?.target ?? input?.list;
-                const idx = input?.index ?? input?.key;
-                if (Array.isArray(target))
-                    return target[idx];
-                if (target && typeof target === 'object')
-                    return target[idx];
-                if (typeof target === 'string')
-                    return target[idx];
-                return null;
-            }
-            // Bitwise
-            case 'bitwise_and': return (this.toNum(left) | 0) & (this.toNum(right) | 0);
-            case 'bitwise_or': return (this.toNum(left) | 0) | (this.toNum(right) | 0);
-            case 'bitwise_xor': return (this.toNum(left) | 0) ^ (this.toNum(right) | 0);
-            case 'bitwise_not': return ~(this.toNum(value ?? input) | 0);
-            case 'left_shift': return (this.toNum(left) | 0) << (this.toNum(right) | 0);
-            case 'right_shift': return (this.toNum(left) | 0) >> (this.toNum(right) | 0);
-            // Null
-            case 'null_coalesce': return left ?? right;
-            // Misc
-            case 'paren': return value ?? input;
-            case 'string_interpolation': return String(value ?? input);
-            case 'int_to_string': return String(Math.trunc(this.toNum(value ?? input)));
-            case 'double_to_string': return String(this.toNum(value ?? input));
-            case 'string_to_int': return parseInt(String(value ?? input));
-            case 'string_to_double': return parseFloat(String(value ?? input));
-            case 'length': return (value ?? input)?.length ?? 0;
-            default:
-                throw new BallRuntimeError(`Unknown base function: ${module}.${fn}`);
-        }
-    }
-    // ── Helpers ───────────────────────────────────────────────────────────
-    typeMatches(value, type) {
-        if (type === undefined || type === null)
-            return false;
-        // Primitive type checks
-        switch (type) {
-            case 'int': return typeof value === 'number' && Number.isInteger(value);
-            case 'double': return typeof value === 'number';
-            case 'num': return typeof value === 'number';
-            case 'String': return typeof value === 'string';
-            case 'bool': return typeof value === 'boolean';
-            case 'List': return Array.isArray(value);
-            case 'Map': return value !== null && typeof value === 'object' && !Array.isArray(value);
-            case 'Null':
-            case 'void': return value === null || value === undefined;
-            case 'Object':
-            case 'dynamic': return true;
-            case 'Function': return typeof value === 'function';
-        }
-        // Check BallObject __type__ and walk __super__ chain
-        if (value && typeof value === 'object' && !Array.isArray(value)) {
-            if (this.typeNameMatches(value.__type__, type))
-                return true;
-            let superObj = value.__super__;
-            while (superObj && typeof superObj === 'object' && !Array.isArray(superObj)) {
-                if (this.typeNameMatches(superObj.__type__, type))
-                    return true;
-                superObj = superObj.__super__;
-            }
-        }
-        // Fallback: JS typeof check
-        return typeof value === type;
-    }
-    typeNameMatches(objType, checkType) {
-        if (!objType)
-            return false;
-        if (objType === checkType)
-            return true;
-        // objType is "module:Foo", checkType is "Foo"
-        if (objType.endsWith(':' + checkType))
-            return true;
-        // objType is "Foo", checkType is "module:Foo"
-        if (checkType.endsWith(':' + objType))
-            return true;
-        return false;
-    }
-    toBool(v) {
-        if (v === null || v === undefined || v === false || v === 0 || v === '')
-            return false;
-        return true;
-    }
-    toNum(v) {
-        if (typeof v === 'number')
-            return v;
-        if (typeof v === 'string')
-            return Number(v) || 0;
-        if (typeof v === 'boolean')
-            return v ? 1 : 0;
-        return 0;
-    }
-    numOp(left, right, op) {
-        return op(this.toNum(left), this.toNum(right));
-    }
-    ballToString(v) {
-        if (v === null || v === undefined)
-            return 'null';
-        if (typeof v === 'number') {
-            return Number.isInteger(v) ? v.toString() : v.toString();
-        }
-        if (typeof v === 'boolean')
-            return v.toString();
-        if (Array.isArray(v))
-            return `[${v.map(x => this.ballToString(x)).join(', ')}]`;
-        if (typeof v === 'object')
-            return JSON.stringify(v);
-        return String(v);
+        return this._output;
     }
 }
+// Re-export useful compiled-engine types for advanced consumers.
+export { StdModuleHandler } from "./compiled_engine.js";
 //# sourceMappingURL=index.js.map