openscad-cpp-evaluator 0.13.2__tar.gz → 0.13.4__tar.gz

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/PKG-INFO

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

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/include/openscad_cpp_evaluator/bytecode.hpp

@@ -325,8 +325,50 @@ enum class Op {
     // same seam, now a counter).
     PopBuiltinWrap,
 
+    // A `children()` / `children(N)` statement -- the runtime-varying
+    // sibling of Op::CallModule/Op::PushBuiltinWrap, closing the LAST
+    // dominant native-reentry source (BOSL2's attachable() calls
+    // children() at nearly every wrapper level; measured 85 of 93 native
+    // reentries in a real script). Unlike PushBuiltinWrap's constructs,
+    // the forwarded children aren't known at compile time (they're the
+    // CALLER's own call-site statements, carried on ctx.childrenNodes/
+    // childrenCallerCtx -- see Evaluator::buildModuleChildCtx), so they
+    // can't compile inline; instead the handler resolves the list at
+    // RUNTIME, looks up/compiles its chunk (the same
+    // childrenListChunkCache_ tryRunCompiledChildren uses, via
+    // lookupOrCompileChildrenListChunk -- gated on useBytecodeVm() &&
+    // inResolvePass_, the cache is pass-scoped), and pushes it onto
+    // vmCallStack_ directly, mirroring Op::CallModule's own zero-native-
+    // call push -- but with a THIRD frame shape: splice-owning like a
+    // module frame (ownsModuleSplice=true, mirroring evalModularCall's
+    // own unconditional splice branch for "children"), yet bracketless
+    // like a bare frame (children() never gets a callStack_/profiling
+    // entry natively either -- only enterUserCall pushes those, and
+    // resolveChildren/builtinChildren never call it). driveVm's existing
+    // completion branch and teardownVmCallStackDownTo both already
+    // handle that combination (their bracket and splice concerns are
+    // independent).
+    //
+    // Handler ordering is load-bearing: checkDebug fires in-handler
+    // against the scope-wrapped ctx (byte-for-byte what Op::
+    // NativeStatement does -- NOT via an emitted Op::CheckDebugStatement,
+    // whose handler passes the un-wrapped ctx); randsBefore is captured
+    // BEFORE argument resolution (rands-in-args taint, same lesson
+    // PushBuiltinWrap already encodes); and treeStack_ is pushed LAST,
+    // immediately before the frame push / native fallback (an early-out
+    // or a throw during arg resolution then has nothing to clean up --
+    // the native path's own catch{pop;throw} has no equivalent here, so
+    // the reorder IS the exception-safety mechanism). The not-eligible
+    // fallback reuses the ALREADY-resolved args (never evalStatement,
+    // which would re-resolve them: double rands(), double side effects)
+    // by inlining evalModularCall's own children branch around a native
+    // evalChildren call. a = index into CompiledChunk::nativeStatements
+    // (the ModularCall node -- arguments, error position, splice node;
+    // no separate site table needed).
+    CallChildren,
+
     // A single "native passthrough" statement -- intersection_for,
-    // children(), union/difference/intersection and every other builtin
+    // union/difference/intersection and every other builtin
     // module call NOT covered by Op::PushBuiltinWrap (see that op's own
     // doc comment for exactly which builtins ARE covered), the `*`
     // modifier's own no-op case, or a user-module call that didn't
@@ -344,7 +386,9 @@ enum class Op {
     // pattern that made this op's own native reentry a genuine Windows
     // crash risk in practice, not just a missed optimization. See
     // Op::PushBuiltinWrap's own doc comment for the real story and the
-    // fix.)
+    // fix. children() fell here too, and was the LAST and largest such
+    // reentry source once PushBuiltinWrap's own set was covered -- it
+    // now has Op::CallChildren, above.)
     // 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,

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -271,6 +271,25 @@ public:
     // _builtin_children/_eval_children_lazy.
     void builtinChildren(const CallArgs& args, EvalContext& ctx);
 
+    // The "which nodes, evaluated against what context" half of
+    // builtinChildren, shared with Op::CallChildren's runtime handler
+    // (bytecode_vm.cpp) so the native and compiled paths cannot drift on
+    // any of the subtle parts: the caller-ctx re-derivation, the
+    // $-forwarding loop (which must read the post-resolveCallArgs effCtx
+    // -- a children($fn=12) named-$ override lives only there), and the
+    // children(N) statement-index filtering/bounds-check. nullopt means
+    // "nothing to evaluate" (no forwarded children in scope, empty list,
+    // or index out of range) -- a silent no-op in every existing caller,
+    // exactly matching builtinChildren's own early returns. `ctx` must be
+    // the effCtx resolveCallArgs returned, same as builtinChildren's own
+    // parameter today. Public for the same free-function reasoning as
+    // builtinChildren itself.
+    struct ChildrenForward {
+        EvalContext evalCtx;
+        std::vector<const oscad::ASTNode*> nodes;
+    };
+    std::optional<ChildrenForward> prepareChildrenForward(const CallArgs& args, EvalContext& ctx);
+
     // "WARNING: {message}{locSuffix(position)}" via echoFn_, no-op if unset.
     // Public: builtins/import.cpp's not-manifold warning is emitted from a
     // free function, same reasoning as tagGenerated()/builtinChildren().
@@ -532,6 +551,17 @@ private:
     // into the caller's scope exactly the way the native per-statement
     // loop's own writes already do.
     bool tryRunCompiledChildren(const std::vector<const oscad::ASTNode*>& children, EvalContext& ctx);
+public:
+    // The cache-lookup half of tryRunCompiledChildren, shared with
+    // Op::CallChildren's runtime handler (bytecode_vm.cpp, a free
+    // function -- public for the same no-friend-declaration reasoning as
+    // vmCallStack_/treeStack_). Returns the eligible compiled chunk for
+    // `children` or nullptr. Caller owns the useBytecodeVm()/
+    // inResolvePass_ gate -- the pass gate is load-bearing
+    // (childrenListChunkCache_ is pass-scoped, see its own doc comment),
+    // not defensive.
+    const CompiledChunk* lookupOrCompileChildrenListChunk(const std::vector<const oscad::ASTNode*>& children);
+private:
     void evalModularCall(const oscad::ModularCall& node, EvalContext& ctx);
     void evalFor(const oscad::ModularFor& node, EvalContext& ctx);
     void evalLetBlock(const oscad::ModularLet& node, EvalContext& ctx);
@@ -951,15 +981,38 @@ private:
     // body -- so a resolvable module call anywhere in that list gets
     // Op::CallModule bytecode, and any if/for control flow around it gets
     // real Jump-based bytecode too, instead of falling through to the
-    // native per-statement loop. Keyed by the list's own FIRST element,
-    // same convention as assignBlockChunkCache_ (stable and unique per
-    // list: a given evalChildren() call site is always handed the same
-    // leading element across repeated evaluations). Same nullopt-means-
+    // native per-statement loop.
+    //
+    // Keyed by (FIRST element, list SIZE) -- NOT the first element alone,
+    // the original convention borrowed from assignBlockChunkCache_
+    // (where it IS sufficient: a leading-assignment run's first member
+    // uniquely determines the run). Here it wasn't: children()'s
+    // forwarding produces two DIFFERENT lists sharing a first element --
+    // bare `children()` forwards the caller's whole list, `children(0)`
+    // a single-element slice of it -- and keying by front alone made
+    // whichever form ran first poison the cache for the other (caught
+    // for real: `module m() { children(); children(0); }\n
+    // m() { cube(); sphere(); }` made children(0) emit BOTH shapes,
+    // or bare children() emit only one, depending on statement order).
+    // (front, size) fully disambiguates every real producer: fixed AST
+    // lists have unique fronts per call site, and the only same-front
+    // pair (bare vs indexed forwarding) always differs in size except
+    // when the lists are literally identical anyway. Same nullopt-means-
     // tried-and-failed convention, same dangling-pointer hazard, same
     // two-part fix (cleared alongside stmtExprChunkCache_ at the top of
     // every resolveTreeImpl call, only read/written while inResolvePass_)
     // as stmtExprChunkCache_ itself.
-    std::unordered_map<const oscad::ASTNode*, std::optional<CompiledChunk>> childrenListChunkCache_;
+    struct ChildrenListKeyHash {
+        size_t operator()(const std::pair<const oscad::ASTNode*, size_t>& k) const {
+            // Standard hash-combine (boost-style golden-ratio mix) --
+            // either half alone collides by construction here.
+            const size_t h1 = std::hash<const oscad::ASTNode*>{}(k.first);
+            const size_t h2 = std::hash<size_t>{}(k.second);
+            return h1 ^ (h2 + 0x9e3779b97f4a7c15ULL + (h1 << 6) + (h1 >> 2));
+        }
+    };
+    std::unordered_map<std::pair<const oscad::ASTNode*, size_t>, std::optional<CompiledChunk>, ChildrenListKeyHash>
+        childrenListChunkCache_;
 
     // See stmtExprChunkCache_'s own doc comment, immediately above, for why
     // this exists. Not a reentrancy guard (resolveTreeImpl is never called
@@ -1115,6 +1168,17 @@ public:
         return bytecodeVmEnabled() && (!debugHooks_.debugHook || fastContinueBreakpoints_.has_value());
     }
 
+    // Read accessor for inResolvePass_ (private, below) -- Op::CallChildren's
+    // runtime handler (bytecode_vm.cpp, a free function) must gate its
+    // childrenListChunkCache_ access on it, exactly like
+    // tryRunCompiledChildren's own self-gate: the cache is pass-scoped
+    // (cleared per resolveTreeImpl, AST-address-reuse hazard -- see
+    // stmtExprChunkCache_'s own doc comment), and driveVm CAN run outside
+    // the resolve pass (a host calling evalChildren directly reaches
+    // module opcodes via lookupOrCompileModuleChunk, which is NOT
+    // pass-scoped).
+    bool inResolvePass() const { return inResolvePass_; }
+
 private:
     // The fine-grained half of the check above: even when useBytecodeVm()
     // says compiling/using bytecode is on the table at all, a SPECIFIC
@@ -1218,6 +1282,12 @@ public:
         // and callStack_.back() is already gone by the time it runs. See
         // activeDeclRefcount_'s own doc comment.
         const oscad::ASTNode* declNode = nullptr;
+        // True only when THIS call incremented nativeUserCallDepth_ (i.e.
+        // skipDepthGuard was false) -- exitUserCall* needs it to decrement
+        // symmetrically, for the same "callStack_.back() is already gone"
+        // reason as `kind`/`declNode` above. See nativeUserCallDepth_'s
+        // own doc comment for why this can't just be "always decrement".
+        bool countedTowardNativeDepth = false;
     };
     // `skipDepthGuard`: kMaxUserCallDepth=50 exists purely to keep the
     // NATIVE C++ stack from overflowing (see its own doc comment) -- true
@@ -1427,6 +1497,37 @@ private:
     // eval_error.hpp).
     std::vector<CallStackFrame> callStack_;
 
+    // Count of callStack_ entries that ACTUALLY cost native C++ stack --
+    // i.e. pushed with skipDepthGuard=false (enterUserCall's own
+    // interpreted-call sites: evalUserFunctionCore, evalUserModule).
+    // Deliberately NOT the same number as callStack_.size(): a compiled-
+    // to-compiled push (pushBracketedCallFrame/pushBracketedModuleFrame,
+    // bytecode_vm.cpp, skipDepthGuard=true) still grows callStack_ (for
+    // TRACE/closure-detection/$parent_modules bookkeeping) but costs ZERO
+    // native stack, serviced by driveVm's own heap-based loop instead.
+    //
+    // Checking callStack_.size() itself against kMaxUserCallDepth (the
+    // ORIGINAL design) conflates these two: a real BOSL2 script's own
+    // AMBIENT callStack_ depth, inflated by many cheap skip=true compiled
+    // module-call pushes sitting on callStack_ already, could push a
+    // LATER genuinely-native-recursive call (e.g. an interpreted-path
+    // function call like BOSL2's own `ident()`) over the threshold even
+    // though the REAL native C++ nesting at that point was nowhere near
+    // it -- caught for real: Anklet.scad's own ambient callStack_ depth
+    // (mostly cheap Op::CallModule pushes) reached the mid-30s, tripping
+    // kMaxUserCallDepth=30 for an `ident()` call that itself was nested
+    // only a couple of GENUINE native frames deep. Exactly the same class
+    // of "fixed-count guard conflates logical depth with native-stack
+    // cost" bug driveVmNativeDepth_ already exists to avoid for the
+    // OTHER guard site (bytecode_vm.cpp) -- this is that same fix,
+    // applied here. Incremented/decremented symmetrically by
+    // enterUserCall/exitUserCallSuccess/exitUserCallException, gated on
+    // UserCallHandle::countedTowardNativeDepth (skipDepthGuard is only
+    // available at enter time; the handle carries the decision forward
+    // to exit time, since callStack_.back() -- and thus skipDepthGuard's
+    // own original context -- is already gone by then).
+    size_t nativeUserCallDepth_ = 0;
+
     // Running count of Module-kind frames currently on callStack_ --
     // maintained incrementally by enterUserCall/exitUserCall* rather than
     // rescanned from callStack_ on every module call (buildModuleChildCtx's

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/include/openscad_cpp_evaluator/scope_trail.hpp

@@ -368,12 +368,30 @@ public:
         dirty_[level].push_back(id);
     }
 
+    // Level-aware, NOT a blind pop_back() -- the exact fix
+    // ScopeTrailStorage::popLevel (above) already carries, for the exact
+    // out-of-order-pop bug class its own doc comment describes; this
+    // indexed twin never got the same fix because nothing violated LIFO
+    // view destruction on the dyn trail until Op::CallChildren's
+    // forwarding frame (bytecode_vm.cpp): its evalCtx (a dyn level opened
+    // AFTER the call's own effCtx level) is moved into a VmFrame and
+    // OUTLIVES effCtx, so effCtx's pop runs while evalCtx's later entry
+    // is still physically on top of the same name's stack -- the blind
+    // pop_back() silently removed the still-live forwarded value instead
+    // of the one actually being popped (caught for real: a
+    // children($fn=9) named-$ override read back as the root default 0
+    // inside the forwarded child).
     void popLevel(int level) {
         auto it = dirty_.find(level);
         if (it != dirty_.end()) {
             for (int id : it->second) {
                 auto& stack = stacks_[static_cast<size_t>(id)];
-                if (!stack.empty()) stack.pop_back();
+                for (auto rit = stack.rbegin(); rit != stack.rend(); ++rit) {
+                    if (rit->level == level) {
+                        stack.erase(std::next(rit).base());
+                        break;
+                    }
+                }
             }
             dirty_.erase(it);
         }

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openscad_cpp_evaluator"
-version = "0.13.2"
+version = "0.13.4"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/src/bytecode_compiler.cpp

@@ -1420,12 +1420,25 @@ public:
                     emitBuiltinWrap(*wrapKind, call.name->name, call, children, out);
                     return;
                 }
-                // Every other builtin, children(), or a name that didn't
-                // resolve to a user module statically -- native
-                // passthrough, exactly like echo/assert/etc. below. Never
-                // the recursion-depth risk this compiler targets for
-                // THESE (see NativeStatement's own doc comment,
-                // bytecode.hpp).
+                // children() -- the runtime-varying forwarding builtin,
+                // detected by the same function-pointer-identity pattern
+                // as Transform/Color above. Deliberately NO preceding
+                // Op::CheckDebugStatement (unlike emitBuiltinWrap's own
+                // emission): CallChildren's handler fires checkDebug
+                // itself against the SCOPE-WRAPPED ctx, byte-for-byte
+                // matching Op::NativeStatement's own handler -- the
+                // CheckDebugStatement handler passes the un-wrapped ctx,
+                // which would be a subtle behavior change for this node.
+                // See Op::CallChildren's own doc comment (bytecode.hpp).
+                if (dispatchIt != dispatch.end() && dispatchIt->second == &resolveChildren) {
+                    out.push_back({Op::CallChildren, internNativeStatement(&stmt), 0, &stmt.position()});
+                    return;
+                }
+                // Every other builtin, or a name that didn't resolve to a
+                // user module statically -- native passthrough, exactly
+                // like echo/assert/etc. below. Never the recursion-depth
+                // risk this compiler targets for THESE (see
+                // NativeStatement's own doc comment, bytecode.hpp).
                 out.push_back({Op::NativeStatement, internNativeStatement(&stmt), 0, &stmt.position()});
                 return;
             }

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/src/bytecode_vm.cpp

@@ -329,6 +329,49 @@ void pushBracketedModuleFrame(Evaluator& ev, const CompiledChunk& chunk, const o
     ev.vmCallBrackets_.push_back(std::move(handle));
 }
 
+// Op::CallChildren's own push -- a THIRD frame shape, distinct from both
+// existing helpers: splice-owning like pushBracketedModuleFrame's
+// (ownsModuleSplice=true, mirroring evalModularCall's own unconditional
+// splice branch for "children", csg_resolve.cpp) but BRACKETLESS like
+// pushBareFrame's (nullopt in vmCallBrackets_ -- children() never gets a
+// callStack_/profiling entry natively either: only enterUserCall pushes
+// those, and resolveChildren/builtinChildren never call it, so no TRACE
+// frame, no profile site, no $parent_modules bump, exactly matching the
+// native path). driveVm's completion branch and teardownVmCallStackDownTo
+// both already handle this combination -- their bracket (`if (bracket)`)
+// and splice (`if (ownsModuleSplice)`) concerns are independent at both
+// sites. `evalCtx` is prepareChildrenForward's result (the caller-derived,
+// $-forwarded context the children must run under -- see that helper's
+// own doc comment, evaluator.hpp). hopEligible set explicitly false --
+// pushBracketedModuleFrame itself omits the reset (benign there only
+// because module chunks never contain tail-call opcodes); don't inherit
+// a pooled function frame's stale true here either.
+void pushChildrenForwardFrame(Evaluator& ev, const CompiledChunk& chunk, EvalContext evalCtx,
+                               std::uint64_t randsBefore, const oscad::ASTNode& callNode) {
+    if (ev.vmCallStack_.size() >= Evaluator::kMaxVmCallStackDepth) {
+        ev.error("Recursion too deep while forwarding children()", callNode);
+    }
+    auto frame = ev.acquireVmFrame();
+    frame->chunk = &chunk;
+    frame->code = &chunk.bodyCode;
+    frame->pc = 0;
+    frame->slots.assign(static_cast<size_t>(chunk.numSlots), Value{});
+    frame->stack.clear();
+    frame->bound.clear();
+    frame->accumStack.clear();
+    frame->iterLists.assign(static_cast<size_t>(chunk.numIterLists), IterList{});
+    frame->ctxChain.clear();
+    frame->ctxChain.push_back(std::move(evalCtx));
+    frame->tailHopGuard = 0;
+    frame->logicalName.clear();
+    frame->hopEligible = false;
+    frame->ownsModuleSplice = true;
+    frame->moduleRandsBefore = randsBefore;
+    frame->moduleSpliceCallNode = &callNode;
+    ev.vmCallStack_.push_back(std::move(frame));
+    ev.vmCallBrackets_.emplace_back(std::nullopt);
+}
+
 // Tears down every frame from vmCallStack_'s own top down to (but not
 // including) `floor`, on the exception path -- releases each VmFrame to
 // the pool, tears down its ctxChain back-to-front (never relying on
@@ -933,6 +976,71 @@ Value driveVm(Evaluator& ev, size_t floor) {
                     }
                     break;
                 }
+                case Op::CallChildren: {
+                    // Ordering is load-bearing throughout -- see this op's
+                    // own doc comment (bytecode.hpp): checkDebug against
+                    // the SCOPE-WRAPPED ctx (byte-for-byte what Op::
+                    // NativeStatement does for this same node today);
+                    // randsBefore BEFORE argument resolution (rands-in-args
+                    // taint); treeStack_ pushed LAST, immediately before
+                    // the frame push / native fallback, so an early-out or
+                    // a throw during arg resolution has nothing to clean
+                    // up (the native path's own catch{pop;throw} has no
+                    // equivalent out here -- this reorder IS the
+                    // exception-safety mechanism; arg resolution never
+                    // appends CSG nodes, so pushing after it is
+                    // unobservable).
+                    const auto* callNode =
+                        static_cast<const oscad::ModularCall*>(f.chunk->nativeStatements[static_cast<size_t>(ins.a)]);
+                    EvalContext scopedCtx = ctx.withScope(callNode->scope() ? callNode->scope() : ctx.scope);
+                    ev.checkDebug(*callNode, scopedCtx);
+                    const std::uint64_t randsBefore = ev.randsCallCount();
+                    auto [args, effCtx] = resolveCallArgs(ev, callNode->arguments, scopedCtx);
+                    std::optional<Evaluator::ChildrenForward> fwd = ev.prepareChildrenForward(args, effCtx);
+                    if (!fwd) {
+                        // No forwarded children in scope / empty / index
+                        // out of range -- a silent no-op, exactly matching
+                        // builtinChildren's own early returns.
+                        ++f.pc;
+                        break;
+                    }
+                    // Pass gate is load-bearing, not defensive -- the
+                    // chunk cache is pass-scoped; see inResolvePass()'s
+                    // own doc comment (evaluator.hpp).
+                    const CompiledChunk* chunk = (ev.useBytecodeVm() && ev.inResolvePass())
+                                                     ? ev.lookupOrCompileChildrenListChunk(fwd->nodes)
+                                                     : nullptr;
+                    if (chunk) {
+                        ev.treeStack_.emplace_back();
+                        pushChildrenForwardFrame(ev, *chunk, std::move(fwd->evalCtx), randsBefore, *callNode);
+                        // f.pc deliberately NOT advanced -- resumes when
+                        // the pushed frame completes; driveVm's completion
+                        // branch runs the splice (isModule &&
+                        // ownsModuleSplice), mirroring evalModularCall's
+                        // own "children" splice branch exactly.
+                    } else {
+                        // Fallback reuses the ALREADY-resolved args --
+                        // never evalStatement, which would re-resolve them
+                        // (double rands(), double echo/assert side
+                        // effects, double expr-level debug stops).
+                        // Inlines evalModularCall's own children branch:
+                        // push accumulator, run natively, pop, splice.
+                        // The native evalChildren still self-gates and
+                        // retries tryRunCompiledChildren internally.
+                        ev.treeStack_.emplace_back();
+                        try {
+                            ev.evalChildren(fwd->nodes, fwd->evalCtx);
+                        } catch (...) {
+                            ev.treeStack_.pop_back();
+                            throw;
+                        }
+                        std::vector<std::unique_ptr<CSGNode>> children = std::move(ev.treeStack_.back());
+                        ev.treeStack_.pop_back();
+                        ev.spliceModuleChildren(std::move(children), randsBefore, *callNode);
+                        ++f.pc;
+                    }
+                    break;
+                }
                 case Op::PushBuiltinWrap: {
                     const CompiledChunk::BuiltinWrapSite& site = f.chunk->builtinWrapSites[static_cast<size_t>(ins.a)];
                     // Captured BEFORE any argument resolution -- mirrors

{openscad_cpp_evaluator-0.13.2 → openscad_cpp_evaluator-0.13.4}/src/user_calls.cpp

@@ -84,15 +84,29 @@ bool Evaluator::tryRunCompiledAssignmentBlock(const std::vector<const oscad::AST
 
 bool Evaluator::tryRunCompiledChildren(const std::vector<const oscad::ASTNode*>& children, EvalContext& ctx) {
     if (children.empty() || !useBytecodeVm() || !inResolvePass_) return false;
+    const CompiledChunk* chunk = lookupOrCompileChildrenListChunk(children);
+    if (!chunk) return false;
+    runCompiledModuleBody(*this, *chunk, ctx);
+    return true;
+}
+
+// The cache-lookup half of tryRunCompiledChildren, shared with
+// Op::CallChildren's own runtime handler (bytecode_vm.cpp) -- both need
+// exactly this "list -> eligible chunk or nullptr" step, differing only
+// in how they then RUN the chunk (native runCompiledModuleBody reentry
+// here, a direct vmCallStack_ push there). Caller is responsible for the
+// useBytecodeVm()/inResolvePass_ gate (see childrenListChunkCache_'s own
+// doc comment for why the pass gate is load-bearing, not defensive).
+const CompiledChunk* Evaluator::lookupOrCompileChildrenListChunk(const std::vector<const oscad::ASTNode*>& children) {
     const oscad::ASTNode* first = children.front();
-    auto it = childrenListChunkCache_.find(first);
+    const auto key = std::make_pair(first, children.size());
+    auto it = childrenListChunkCache_.find(key);
     if (it == childrenListChunkCache_.end()) {
-        it = childrenListChunkCache_.emplace(first, tryCompileChildrenList(children, first->scope())).first;
+        it = childrenListChunkCache_.emplace(key, tryCompileChildrenList(children, first->scope())).first;
         if (it->second) flattenNestedLiterals(*it->second);
     }
-    if (!it->second || !chunkEligibleNow(*it->second)) return false;
-    runCompiledModuleBody(*this, *it->second, ctx);
-    return true;
+    if (!it->second || !chunkEligibleNow(*it->second)) return nullptr;
+    return &*it->second;
 }
 
 const Value* Evaluator::findUpvalue(const oscad::ASTNode* targetDecl, int slot) const {
@@ -682,13 +696,22 @@ Evaluator::UserCallHandle Evaluator::enterUserCall(const std::string& name, cons
     // entirely; for what's left, the margin check is the proven-UNSAFE
     // mechanism on Windows (confirmed via real CI), this fixed count the
     // proven-safe one.
-    if (!skipDepthGuard && callStack_.size() >= kMaxUserCallDepth) {
+    //
+    // Checked against nativeUserCallDepth_, NOT callStack_.size() -- see
+    // that field's own doc comment (evaluator.hpp) for why: callStack_
+    // also grows from cheap, zero-native-cost skipDepthGuard=true pushes,
+    // which must not count toward this native-stack-safety ceiling.
+    if (!skipDepthGuard && nativeUserCallDepth_ >= kMaxUserCallDepth) {
         error("Recursion too deep while calling " + std::string(isModule ? "module" : "function") + " '" + name + "'",
               declNode);
     }
     UserCallHandle h;
     h.kind = kind;
     h.declNode = &declNode;
+    if (!skipDepthGuard) {
+        ++nativeUserCallDepth_;
+        h.countedTowardNativeDepth = true;
+    }
     h.prof = profileEnter(isModule ? "module" : "function", name, callPos, &declNode.position());
     callStack_.push_back(CallStackFrame{kind, name, callPos, &declNode.position(), &declNode, nullptr, upvalueParent});
     callStack_.back().bodyCtx = &childCtx; // per-frame locals for the debugger
@@ -710,6 +733,7 @@ void Evaluator::exitUserCallSuccess(const std::string& name, const UserCallHandl
     if (fireReturnHook && debugHooks_.returnHook) debugHooks_.returnHook(name, result, static_cast<int>(callStack_.size()));
     callStack_.pop_back();
     if (handle.kind == CallStackFrame::Kind::Module) --moduleCallDepth_;
+    if (handle.countedTowardNativeDepth) --nativeUserCallDepth_;
     noteActiveDeclExit(handle.declNode);
     if (handle.prof) profileExit(*handle.prof);
 }
@@ -717,6 +741,7 @@ void Evaluator::exitUserCallSuccess(const std::string& name, const UserCallHandl
 void Evaluator::exitUserCallException(const UserCallHandle& handle) {
     callStack_.pop_back();
     if (handle.kind == CallStackFrame::Kind::Module) --moduleCallDepth_;
+    if (handle.countedTowardNativeDepth) --nativeUserCallDepth_;
     noteActiveDeclExit(handle.declNode);
     if (handle.prof) profileExit(*handle.prof);
 }
@@ -886,15 +911,20 @@ Value Evaluator::parentModuleName(int idx) const {
     return Value{modules[static_cast<size_t>(revIdx)]};
 }
 
-void Evaluator::builtinChildren(const CallArgs& args, EvalContext& ctx) {
+std::optional<Evaluator::ChildrenForward> Evaluator::prepareChildrenForward(const CallArgs& args, EvalContext& ctx) {
     Value idxArg = getArg(args, 0, "index", Value{});
-    if (!ctx.childrenNodes || ctx.childrenNodes->empty()) return;
+    if (!ctx.childrenNodes || ctx.childrenNodes->empty()) return std::nullopt;
     const EvalContext* callerCtx = ctx.childrenCallerCtx;
-    if (!callerCtx) return;
+    if (!callerCtx) return std::nullopt;
 
     // A children() forwarding chain's own dyn/let_/etc. must alias the
     // *caller's* (not this ctx's) -- see EvalContext::withScope's rationale.
     EvalContext evalCtx = callerCtx->childCtx(nullptr, std::nullopt, callerCtx->childrenNodes, callerCtx->childrenCallerCtx);
+    // `ctx` here is the post-resolveCallArgs effCtx, deliberately: a
+    // `children($fn=12)`-style named-$ override lives only at effCtx's own
+    // trail level, and TrailView::items() is ancestry-visible, so reading
+    // from effCtx forwards both the call's own overrides AND everything
+    // the wrapper module's body set (`$fn = 100; children();`).
     for (const auto& [k, v] : ctx.dyn->items()) {
         if (!k.empty() && k[0] == '$') evalCtx.dyn->set(k, v);
     }
@@ -903,8 +933,7 @@ void Evaluator::builtinChildren(const CallArgs& args, EvalContext& ctx) {
     }
 
     if (std::holds_alternative<std::monostate>(idxArg)) {
-        evalChildren(*ctx.childrenNodes, evalCtx);
-        return;
+        return ChildrenForward{std::move(evalCtx), *ctx.childrenNodes};
     }
 
     // children(N) indexes child *statements*, not output bodies -- a
@@ -919,8 +948,14 @@ void Evaluator::builtinChildren(const CallArgs& args, EvalContext& ctx) {
             geoNodes.push_back(c);
         }
     }
-    if (idx < 0 || static_cast<size_t>(idx) >= geoNodes.size()) return;
-    evalChildren(std::vector<const oscad::ASTNode*>{geoNodes[static_cast<size_t>(idx)]}, evalCtx);
+    if (idx < 0 || static_cast<size_t>(idx) >= geoNodes.size()) return std::nullopt;
+    return ChildrenForward{std::move(evalCtx), {geoNodes[static_cast<size_t>(idx)]}};
+}
+
+void Evaluator::builtinChildren(const CallArgs& args, EvalContext& ctx) {
+    std::optional<ChildrenForward> fwd = prepareChildrenForward(args, ctx);
+    if (!fwd) return;
+    evalChildren(fwd->nodes, fwd->evalCtx);
 }
 
 } // namespace oscadeval