openscad-cpp-evaluator 0.9.2__tar.gz → 0.13.0__tar.gz

{openscad_cpp_evaluator-0.9.2 → openscad_cpp_evaluator-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_cpp_evaluator
-Version: 0.9.2
+Version: 0.13.0
 Summary: C++ OpenSCAD evaluator with Python bindings
 Author: NeuSCAD Contributors
 License-Expression: MIT

{openscad_cpp_evaluator-0.9.2 → openscad_cpp_evaluator-0.13.0}/include/openscad_cpp_evaluator/bytecode.hpp

@@ -12,6 +12,10 @@
 namespace oscad {
 class FunctionDeclaration;
 class FunctionLiteral;
+class ModuleDeclaration;
+class ModularCall;
+class ModularAssert;
+class Expression;
 } // namespace oscad
 
 namespace oscadeval {
@@ -37,7 +41,33 @@ enum class Op {
     StoreLocal,     // a = slot index (pops)
     LoadDyn,        // a = name pool index ($-prefixed)
     StoreDyn,       // a = name pool index (pops; also marks dynExplicit)
-    LoadFree,       // a = name pool index -- Evaluator::evalIdentifier fallback
+    LoadFree,       // a = name pool index -- Evaluator::evalIdentifier fallback (warnIfUndef=true)
+    // Same as LoadFree, but Evaluator::evalIdentifier's warnIfUndef=false --
+    // only ever emitted for a PrimaryCall's own callee probe (bytecode_
+    // compiler.cpp's PrimaryCall case), mirroring evalFunctionCall's own
+    // `evalIdentifier(leftId->name, ..., /*warnIfUndef=*/false)` fallback
+    // exactly: probing whether a bare identifier resolves to a callable
+    // Closure value shouldn't itself warn "unknown variable" when it
+    // doesn't -- Op::CallDynamic's own runtime handler already warns
+    // "unknown function" once the probe comes back non-Closure, so using
+    // plain LoadFree here doubled that up into two warnings for one
+    // genuinely-unknown callee.
+    LoadFreeNoWarn, // a = name pool index
+    // a = slot index, b = name pool index (pops). Only emitted for a
+    // compiled ASSIGNMENT BLOCK (Evaluator::tryCompileAssignmentBlock,
+    // user_calls.cpp -- a run of sibling `name = expr;` statements sharing
+    // one scope, exactly what Evaluator::evalChildren already isolates as
+    // its own `assignments` sub-list before any non-assignment statement
+    // runs). Stores into BOTH the slot (so a LATER sibling assignment in
+    // the SAME batch can read this one back via a fast LoadLocal, mirroring
+    // how LetOp's own bindings already work) AND ctx.let_ (so code OUTSIDE
+    // this compiled batch -- a later non-assignment statement, a nested
+    // block, a module call -- still sees it the ordinary way, since this
+    // batch's own slots are invisible once it returns). Plain StoreLocal
+    // alone would lose that outer visibility entirely; plain "store to
+    // let_ only" would lose the fast intra-batch slot reads a batch of
+    // assignments exists to buy back in the first place.
+    StoreLocalAndLet,
     Range,          // pops step, pops end, pops start (pushed in that order); pushes applyRange(start, end, step)
     Index,          // pops idx, pops obj, pushes applyIndexAccess(obj, idx)
     Member,         // a = name pool index (member name); pops obj, pushes applyMemberAccess(obj, name)
@@ -210,6 +240,206 @@ enum class Op {
     // which recomputes this on every failing call). pos/node: same
     // Evaluator::error() TRACE-walk need CheckIterLimit already has.
     AssertFail,
+
+    // -- Module-body compilation (Stage 2) --------------------------------
+    // A call to a user module resolved to a specific ModuleDeclaration AT
+    // COMPILE TIME (see CompiledChunk::ModuleCallSite) -- the module-side
+    // analog of Op::CallFn. a = index into CompiledChunk::moduleCallSites.
+    // Arguments are NOT pre-pushed onto the operand stack the way CallFn's
+    // are (bindArgs runs directly against site.callNode->arguments at
+    // runtime instead) -- module-call argument evaluation was never the
+    // recursion-safety target here, so there's no need to teach the
+    // compiler a separate "push each arg" step just for this. Produces no
+    // stack Value at all: its effect is entirely the side effect of
+    // splicing (or wrapping into a synthetic "union") whatever CSGNodes
+    // the callee's body produces into the CURRENT treeStack_ frame -- see
+    // Evaluator::spliceModuleChildren's own doc comment (bytecode_vm.cpp)
+    // for why this is always the splice branch, never the "wrap as a
+    // builtin-tagged CSGNode" one evalModularCall's own general form also
+    // has (Op::CallModule only ever targets a resolved USER module, for
+    // which splice is unconditional).
+    CallModule,
+
+    // A single "native passthrough" statement -- a modifier wrapper,
+    // intersection_for, children(), a builtin module call, or a user-
+    // module call that didn't resolve at compile time (shadowed, forward-
+    // declared, or otherwise not statically known) -- anything
+    // compileStatementList doesn't give its own real bytecode. (Assignment/
+    // ModularEcho/ModularAssert/ModularLet used to fall here too; they now
+    // have their own real bytecode -- Op::StoreModuleVar/Op::Echo/
+    // Op::AssertStatement/Op::OpenLetScope+StoreLetVar -- purely a
+    // throughput change, since none of these were ever the recursion-depth
+    // risk this compiler targets.)
+    // a = index into CompiledChunk::nativeStatements. Runtime just does
+    // what Evaluator::evalChildren's own per-statement loop already does
+    // for one node: derive childCtx via ctx.withScope(...), checkDebug,
+    // evalStatement. These are "leaf-shaped" in the sense the Stage 2 plan
+    // means it: whatever native recursion they make (a builtin's own
+    // resolve function walking ITS children, etc.) is bounded by ordinary
+    // script structure, not by how deep a recursive module chain goes --
+    // that risk is fully covered by CallModule/ForIterNext/the Jump-based
+    // if/for control flow instead, regardless of how many of THESE sit
+    // alongside them in the same body.
+    NativeStatement,
+
+    // If/if-else's own condition, evaluated NATIVELY (Evaluator::
+    // evalExprMaybeCompiled -- gets the SAME expression-level compilation
+    // a bare statement-context expression already would, just not folded
+    // into THIS chunk's own instruction stream) rather than compiled
+    // inline -- module-body compilation's job is the STATEMENT-level
+    // control flow (so a recursive module call nested inside doesn't hide
+    // behind a native evalStatement call), not re-deriving expression
+    // compilation tryCompileStatementExpr already does. a = index into
+    // CompiledChunk::nativeExprs, b = jump target on false (mirrors
+    // JumpIfFalse's own semantics, just with a native condition source
+    // instead of a popped stack Value).
+    NativeCondJumpIfFalse,
+
+    // The "entering this branch/iteration" expr-level checkDebug marker
+    // ModularIf/ModularIfElse/ModularFor's own interpreted forms each fire
+    // once (see evalStatement's ModularIf/ModularIfElse cases and evalFor,
+    // stmt_eval.cpp) -- a = index into CompiledChunk::nativeStatements
+    // (reusing that same table; the entry here is whichever ASTNode the
+    // interpreter would have passed to checkDebug -- the branch/body's
+    // own first statement, or the ModularIf/For node itself when that
+    // branch/body is empty).
+    NativeCheckDebugExprLevel,
+
+    // One ModularFor assignment's own RHS range/list expression, evaluated
+    // NATIVELY (same reasoning as NativeCondJumpIfFalse) and materialized
+    // into an IterList exactly like the existing (list-comprehension)
+    // Op::IterMaterialize -- a = index into CompiledChunk::nativeExprs, b
+    // = iterList id.
+    NativeIterMaterialize,
+
+    // Statement-for's own per-iteration advance -- the module-body analog
+    // of Op::IterNext, but binding into ctx.let_ (a real, dynamically-
+    // discoverable statement-scope variable, exactly like the
+    // interpreter's own per-iteration childCtx.let_->set()) instead of a
+    // slot, and -- critically -- pushing a FRESH child EvalContext onto
+    // f.ctxChain for the upcoming iteration rather than mutating the
+    // current one in place: evalFor derives a brand-new childCtx per
+    // iteration (see stmt_eval.cpp), so an ordinary local assignment made
+    // inside the loop body doesn't trip evalAssignment's own "was
+    // assigned on line N but overwritten" warning on iteration 2 onward,
+    // and so a value bound in one iteration never leaks into the next.
+    // a = name-pool index (the loop variable's own name), b = iterList id,
+    // c = jump target on exhaustion (taken WITHOUT pushing a new ctx --
+    // mirrors the cartesian loop simply not entering the body once that
+    // dimension is exhausted). `node` = the Assignment AST node, for the
+    // matching per-iteration checkDebug call (mirrors evalFor's own
+    // `checkDebug(*node.assignments[depth], childCtx)`). Always paired
+    // with a matching Op::ForIterEnd at the bottom of the SAME dimension's
+    // loop body.
+    ForIterNext,
+
+    // Pops the ctx Op::ForIterNext just pushed for the iteration that's
+    // ending (f.ctxChain.pop_back()) and jumps back to that same
+    // ForIterNext instruction to attempt the next one. a = jump target
+    // (the matching ForIterNext's own pc).
+    ForIterEnd,
+
+    // -- Module-body leaf-statement compilation (throughput, not a --------
+    // -- recursion-safety concern -- see NativeStatement's own doc comment
+    // for why THAT stayed native for these same node kinds in Stage 2;
+    // this closes the "every sub-expression is a separate nested driveVm
+    // call via evalExprMaybeCompiled" gap instead by inlining them into
+    // the enclosing chunk's own instruction stream) --------------------
+    //
+    // A module-body statement's own top-level checkDebug -- the compiled
+    // analog of what evalChildren's native per-statement loop / Op::
+    // NativeStatement's own handler already does for the SAME node
+    // (`ev.checkDebug(*stmt, ctx)`, exprLevel=false, forced=false) -- kept
+    // as a real op (not simply omitted) so a compiled statement's debug
+    // behavior is identical to its native form, not just "usually doesn't
+    // matter because fast-continue only compiles breakpoint-free chunks."
+    // a = index into CompiledChunk::nativeStatements (reusing that table).
+    CheckDebugStatement,
+
+    // Assignment's own compiled form -- pops one Value (already evaluated
+    // via an ordinary inline compileExpr, NOT native evalExprMaybeCompiled)
+    // and replicates Evaluator::evalAssignment exactly: a `$`-prefixed name
+    // goes to ctx.dyn (+ dynExplicit), everything else checks
+    // ctx.dynPositions for the "assigned but overwritten" warning, then
+    // writes ctx.let_ and records this position. Never slot-addressed --
+    // module-level/top-level assignments are always ctx-visible, dynamic-
+    // scope writes, exactly like today. a = name pool index, pos = the
+    // Assignment node's own position (for both the overwritten warning and
+    // the position recorded into dynPositions).
+    StoreModuleVar,
+
+    // ModularEcho/ModularAssert's own statement form share Op::Echo/a
+    // dedicated AssertStatement op (below) for the "pop N already-compiled
+    // argument values" mechanics -- see those ops' own doc comments
+    // (Op::Echo, above; Op::AssertStatement, below) for why the
+    // EXPRESSION-form opcodes are directly reusable (statement-shaped
+    // already: no value pushed, straight fall-through) while assert's
+    // needs its own op (named-argument support + eager-not-lazy message
+    // evaluation, both genuinely different from AssertOp's own contract).
+
+    // Isolates ONE inline-compiled sub-expression's own `$`-writes from the
+    // rest of this chunk's shared, long-lived ctx -- pushes ctx.
+    // letChildCtx() (reads still see through to the parent level; only
+    // WRITES are isolated) onto f.ctxChain, mirroring exactly what
+    // runCompiledExprChunk's own wrapper already does for a native call
+    // into a compiled EXPRESSION chunk (evalExprMaybeCompiled). Needed
+    // because a module-body statement's own inline-compiled sub-
+    // expression (Assignment's RHS, one echo()/assert() argument) has NO
+    // such wrapper of its own the way a genuinely separate chunk call
+    // does -- without this, `v1 = let($fn=55) f(); v2 = f();` leaks $fn=55
+    // into v2 too (caught for real by UserFunction.
+    // DollarVarLetAsAssignmentRhsDoesNotLeak once Assignment got its own
+    // inline compiled form). Always emitted, unconditionally, around
+    // EVERY such sub-expression -- not just ones statically known to
+    // contain a `let($...)` -- for the same reason runCompiledExprChunk's
+    // own wrapper is unconditional: a nested call/closure could still
+    // reach one indirectly, and the cost when nothing $-scoped is present
+    // is just one cheap trail-level open, not a real expression re-walk.
+    OpenExprScope,
+    // Pops the ctx OpenExprScope just pushed (f.ctxChain.pop_back()) --
+    // always paired, immediately after the sub-expression's own compiled
+    // code finishes (its RESULT, if any, is already on f.stack by then;
+    // this only tears down the ctx, never touches the value stack). Also
+    // reused to close Op::OpenLetScope's own child ctx (below) -- both are
+    // just "pop the current ctx level", identical either way.
+    CloseExprScope,
+
+    // ModularLet's own (statement-form) child scope -- mirrors
+    // Evaluator::evalLetBlock's own `ctx.childCtx(nullptr, std::nullopt,
+    // ctx.childrenNodes, ctx.childrenCallerCtx)` call exactly, pushed onto
+    // f.ctxChain (Op::CloseExprScope, above, pops it back off once the
+    // let-block's own body finishes compiling/running). Every assignment's
+    // own RHS is compiled+evaluated BEFORE this runs (while the PARENT ctx
+    // is still current -- see ModularLet's own compileOneStatement case,
+    // bytecode_compiler.cpp, for why: the statement form's RHS must never
+    // see an EARLIER sibling's own write in the SAME let-block, unlike the
+    // let-EXPRESSION form's sequential visibility), each left on f.stack;
+    // only the WRITES (Op::StoreLetVar, below) happen after this runs.
+    OpenLetScope,
+
+    // Op::StoreLetVar -- pops one value and writes it into the CURRENT ctx
+    // (by then, the child Op::OpenLetScope just pushed) via the same
+    // `$`-prefix branch Op::StoreModuleVar uses, but WITHOUT its
+    // dynPositions "assigned but overwritten" bookkeeping -- evalLetBlock's
+    // own writes never do that check either (a let-block's own child scope
+    // is always fresh, so "reassigning the same name in the same scope"
+    // can never happen the way a module-body Assignment's own can). a =
+    // name pool index, pos = the Assignment node's own position (unused by
+    // the handler itself, kept for consistency/future debugging only).
+    StoreLetVar,
+
+    // a = index into CompiledChunk::assertSites. Pops site.argCount values
+    // (all of this statement's own arguments, already compiled+pushed in
+    // source order via compileExpr -- EVERY one, not just condition/
+    // message, mirrors evalAssertStatement's own eager resolveArgs() over
+    // AssertOp's lazy-message contract) and replicates
+    // Evaluator::evalAssertStatement exactly: named "condition"/"message"
+    // win over positional 0/1 (resolved at COMPILE time into
+    // AssertSite::conditionArgIndex/messageArgIndex -- the argument SHAPE
+    // is static, only values vary per call), throws via Evaluator::error()
+    // on failure, otherwise runs any chained node.children natively (rare;
+    // not worth its own compiled path -- see AssertSite's own doc comment).
+    AssertStatement,
 };
 
 struct Instruction {
@@ -241,7 +471,11 @@ struct Instruction {
 struct CompiledChunk {
     struct Param {
         std::string name;
-        int slot = 0;
+        int slot = 0; // unused when isDyn is true -- $-params are never slot-addressed
+        // $-prefixed parameter: binds through ctx.dyn (dynamically scoped)
+        // instead of a slot -- see compileFunctionLike's own doc comment,
+        // bytecode_compiler.cpp, and bindCompiledArgs', bytecode_vm.cpp.
+        bool isDyn = false;
     };
 
     // A call site statically resolved at compile time (see
@@ -335,6 +569,59 @@ struct CompiledChunk {
         std::vector<std::optional<std::string>> argNames;
     };
 
+    // One Op::CallModule site -- a ModularCall statically resolved (at
+    // compile time, via the enclosing ModuleDeclaration's own static
+    // scope) to a specific user ModuleDeclaration. Unlike CallSite,
+    // there's no isBuiltin/isImport branch to represent: a callee that
+    // ISN'T a resolved user ModuleDeclaration (a builtin, children(), an
+    // unresolvable name) never gets one of these -- it's compiled as a
+    // NativeStatement instead (see Op::CallModule's own doc comment for
+    // why that's exactly right, not a missed optimization).
+    struct ModuleCallSite {
+        const oscad::ModuleDeclaration* decl = nullptr;
+        const oscad::ModularCall* callNode = nullptr;
+        std::string calleeName;
+    };
+
+    // One Op::AssertStatement site -- see that op's own doc comment for
+    // the full contract. `conditionArgIndex`/`messageArgIndex` are indices
+    // into the site's own argCount-sized popped-argument array (source
+    // order), resolved at COMPILE time via the same "named wins over
+    // positional 0/1" priority Evaluator::getArg applies at runtime --
+    // nullopt means "no argument supplies this logical parameter" (mirrors
+    // getArg's own defaultValue fallback: absent condition reads as
+    // `Value{true}`, absent message means no ": ..." suffix).
+    // `condTextConstIdx`: constants[] index of the condition argument's own
+    // source text (or "false" when no condition argument exists, matching
+    // evalAssertStatement's `node.arguments.empty() ? "false" : ...`),
+    // interned once at compile time. `node`: for both Evaluator::error()'s
+    // TRACE walk and the (rare) chained-children fallback below.
+    //
+    // ponytail: a script with TWO named args of the SAME name (e.g.
+    // `assert(condition=true, condition=false)`) would resolve to the
+    // LAST one here, not getArg's own first-match; not worth the extra
+    // bookkeeping to fix for input that's already nonsensical.
+    struct AssertSite {
+        int argCount = 0;
+        std::optional<int> conditionArgIndex;
+        std::optional<int> messageArgIndex;
+        int condTextConstIdx = -1;
+        const oscad::ModularAssert* node = nullptr;
+    };
+
+    // Every distinct chunk this SPECIFIC CompiledChunk owns is either a
+    // function body (bodyCode is one expression's own instruction stream)
+    // or a module body (bodyCode is a compiled STATEMENT list -- see
+    // tryCompileModuleBody, bytecode_compiler.cpp) -- never both. `params`/
+    // `defaultCode` mean the same thing either way (a ModuleDeclaration's
+    // parameters are shaped identically to a FunctionDeclaration's).
+    // Gates driveVm's own frame-completion branch (bytecode_vm.cpp):a
+    // function frame's completion produces a Value (popped off f.stack);
+    // a module frame's produces nothing on the stack at all -- its whole
+    // effect already landed in treeStack_ as a side effect of running its
+    // own body.
+    bool isModule = false;
+
     // The FunctionDeclaration/FunctionLiteral this chunk's own body was
     // compiled from (bytecode_compiler.cpp's compileFunctionLike sets this
     // to its own `selfDecl` parameter) -- Op::MakeClosure's runtime handler
@@ -353,6 +640,13 @@ struct CompiledChunk {
     std::vector<UpvalueRef> upvalues;
     std::vector<ClosureSite> closureSites;
     std::vector<EchoSite> echoSites;
+    // Module-body-only tables (see Op::CallModule/NativeStatement/
+    // NativeCondJumpIfFalse/NativeCheckDebugExprLevel/NativeIterMaterialize's
+    // own doc comments, above) -- always empty for a function chunk.
+    std::vector<ModuleCallSite> moduleCallSites;
+    std::vector<AssertSite> assertSites;
+    std::vector<const oscad::Expression*> nativeExprs;
+    std::vector<const oscad::ASTNode*> nativeStatements;
     int numSlots = 0;
     // Count of distinct ListCompFor-assignment iterLists allocated across
     // this whole chunk (see IterMaterialize/IterReset/IterNext) -- runChunk

openscad_cpp_evaluator-0.13.0/include/openscad_cpp_evaluator/bytecode_compiler.hpp

@@ -0,0 +1,126 @@
+#pragma once
+
+#include "openscad_cpp_evaluator/bytecode.hpp"
+
+#include <optional>
+#include <vector>
+
+namespace oscad {
+class Assignment;
+class FunctionDeclaration;
+class ModuleDeclaration;
+class Expression;
+class Scope;
+} // namespace oscad
+
+namespace oscadeval {
+
+// Attempts to compile `decl`'s parameter defaults + body to bytecode.
+// Returns nullopt if `decl` uses a construct this compiler doesn't handle
+// yet -- the caller falls back to the ordinary AST interpreter for that
+// whole function, unconditionally correct since nothing about this
+// function's behavior changes based on whether it happened to compile.
+std::optional<CompiledChunk> tryCompileFunction(const oscad::FunctionDeclaration& decl);
+
+// Compiles a bare STATEMENT-context expression -- an assignment's RHS, an
+// if/for condition, a module-call or echo()/assert() argument -- rather
+// than a whole function body. No parameters, no enclosing/upvalue chain, no
+// self declaration: every name reference resolves through Op::LoadFree/
+// Op::LoadDyn, the identical ctx.let_/ctx.dyn lookup evalExpr's own
+// Identifier case already does for a statement-level local (a for-loop
+// variable, an assignment-declared name) -- this buys back the AST
+// dispatch overhead compileExpr already saves for functions, not faster
+// variable access (statement-level locals were never slot-addressable to
+// begin with; they're declared by scattered Assignment statements, not a
+// fixed parameter list known in advance). A nested let() inside the
+// expression still gets a real compile-time slot, exactly as it would
+// inside a function body.
+//
+// Refuses to compile (returns nullopt) if the expression creates any
+// closure that captures something (chunk.closureSites non-empty after
+// compileFunctionLike returns) -- with no enclosing chain and no self
+// declaration for this bare wrapper, such a closure's own upvalue
+// resolution would target a CallStackFrame that will never exist (this
+// path pushes none), which is silently WRONG (stale/undef) rather than a
+// safe fallback. Not a hypothetical carve-out: it's the one shape this
+// wrapper cannot support correctly, so it's excluded rather than risked.
+// `scope` is the expression's own lexical scope (Expression::scope(),
+// always set by buildScope() regardless of node kind) -- needed to resolve
+// any callee inside it statically, the same way a function body's call
+// sites are.
+std::optional<CompiledChunk> tryCompileStatementExpr(const oscad::Expression& expr, const oscad::Scope* scope);
+
+// Compiles a run of SIBLING assignment statements sharing one scope --
+// exactly Evaluator::evalChildren's own `assignments` sub-list (stmt_eval.
+// cpp), which OpenSCAD already runs as a self-contained group before any
+// non-assignment statement in the same block. Unlike tryCompileStatementExpr
+// (one independent chunk per leaf expression -- fine for a single
+// assignment, but its own per-call overhead dominated a WHOLE block of
+// them, see this feature's own commit message for the measured regression),
+// this compiles the ENTIRE run as one chunk with one shared CompileScope:
+// each assignment's own name gets a real slot (declared in source order,
+// mirroring LetOp's own sequential-visibility rule -- `y = x + 1;` after
+// `x = 1;` reads `x` via a fast LoadLocal, not a name lookup), and each
+// value is written out via Op::StoreLocalAndLet so code OUTSIDE this batch
+// still sees it the ordinary way (see runCompiledAssignmentBlock's own doc
+// comment, bytecode_vm.hpp, for why `ctx` is used directly, not a scoped
+// child).
+//
+// Refuses to compile (returns nullopt) for any of:
+// - the same plain (non-$) name assigned more than once in this run --
+//   evalAssignment's own "was assigned on line N but overwritten" warning
+//   would otherwise silently stop firing for a reassignment inside a
+//   compiled batch; safer to fall back than to lose it silently.
+// - any closure that captures something (same hazard, same reasoning, as
+//   tryCompileStatementExpr's own doc comment above).
+// - a $-prefixed assignment nested inside a let()/list-comprehension-let
+//   clause ANYWHERE in this run (post-compile: any Op::StoreDyn in the
+//   resulting bodyCode) -- runCompiledAssignmentBlock runs directly against
+//   the caller's own `ctx`, not a scoped child the way a bare expression
+//   chunk gets (letChildCtx(), see runCompiledExprChunk's own doc comment)
+//   -- there is no scope here for that nested let()'s own dyn write to be
+//   contained by, so it would leak into the caller's ctx.dyn permanently
+//   instead of just for that one assignment's own RHS.
+std::optional<CompiledChunk> tryCompileAssignmentBlock(const std::vector<const oscad::Assignment*>& assigns,
+                                                        const oscad::Scope* scope);
+
+// Attempts to compile `decl`'s parameter defaults + STATEMENT-list body
+// (decl.children) to bytecode (Stage 2) -- the module-side analog of
+// tryCompileFunction. Returns nullopt (falls back to the ordinary
+// interpreter for this whole module) for a construct compileStatementList
+// doesn't handle -- see its own doc comment (bytecode_compiler.cpp) for
+// exactly which statement kinds get real bytecode (assignment/if/for/a
+// resolved user-module call) versus a native passthrough (everything
+// else: echo/assert/let-blocks/modifiers/intersection_for/builtin or
+// unresolved module calls) -- the native passthrough shapes never bail
+// compilation of the WHOLE body the way an unsupported EXPRESSION
+// construct does for tryCompileFunction; only a genuinely unsupported
+// EXPRESSION (inside an if-condition/for-range/argument) can still bail
+// (via tryCompileStatementExpr's own NotCompilable, propagated up).
+std::optional<CompiledChunk> tryCompileModuleBody(const oscad::ModuleDeclaration& decl);
+
+// Same compilation (assignment/if/for/resolved-module-call get real
+// bytecode, everything else a native passthrough), but for an ARBITRARY
+// statement list, not just a ModuleDeclaration's own `children` -- the
+// general form behind Evaluator::tryRunCompiledChildren, which every
+// evalChildren() call now tries first (stmt_eval.cpp), including a
+// builtin module's own children (translate()/union()/etc.'s internal
+// evalChildren call, src/builtins/*.cpp) and a for-loop's/let-block's
+// body. This is what actually reaches the "native passthrough wraps a
+// recursive module call" case Op::NativeStatement alone can't -- see this
+// project's own session notes on the Stage 2 "NativeStatement gap" for
+// why a builtin call itself (translate, not just what's declared inside
+// this project's own module bodies) still can't become a SINGLE flat
+// instruction stream with its caller this way (its own resolve function,
+// e.g. resolveTransform, computes params AND evaluates children as one
+// opaque native call -- decoupling that is a separate, larger project),
+// but this DOES mean the children of any wrapping builtin get their own,
+// independent chance to compile, cutting the number of native stack
+// frames needed per recursive "wrap-then-recurse" level rather than
+// eliminating them entirely. `scope`: the list's own lexical scope for
+// resolving a call site's callee -- callers pass `children.front()->
+// scope()`, mirroring tryRunCompiledAssignmentBlock's own convention.
+std::optional<CompiledChunk> tryCompileChildrenList(const std::vector<const oscad::ASTNode*>& children,
+                                                     const oscad::Scope* scope);
+
+} // namespace oscadeval