openscad-cpp-evaluator 1.6.1__tar.gz → 1.7.2__tar.gz

{openscad_cpp_evaluator-1.6.1 → openscad_cpp_evaluator-1.7.2}/PKG-INFO

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

{openscad_cpp_evaluator-1.6.1 → openscad_cpp_evaluator-1.7.2}/include/openscad_cpp_evaluator/bytecode.hpp

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "openscad_cpp_evaluator/function_builtins.hpp"
 #include "openscad_cpp_evaluator/value.hpp"
 
 #include "openscad_cpp_parser/ast/ast_node.hpp"
@@ -787,6 +788,49 @@ struct CompiledChunk {
         const oscad::FunctionDeclaration* decl = nullptr;
         std::vector<std::optional<std::string>> argNames;
         const oscad::ASTNode* callNode = nullptr;
+        // Everything below is `calleeName` already looked up, once, here at
+        // compile time. The VM used to redo all three on EVERY builtin call:
+        // two std::string hashes into static tables plus a string compare
+        // against "object", for answers that cannot change once this site is
+        // compiled. `declaredParams` points into a function-local static
+        // table with process lifetime, so holding the pointer is safe.
+        BuiltinFnId builtinId = BuiltinFnId::None;
+        const std::vector<std::string>* declaredParams = nullptr;
+        bool isObjectBuiltin = false;
+
+        // Where each argument of this call goes, worked out once at compile
+        // time against `decl`'s parameter list -- see ArgBind. Only filled in
+        // for a static user-function callee (`decl` set); a builtin, an
+        // import or a dynamic/closure callee has no compile-time parameter
+        // list to match against and keeps the name-matching path.
+        //
+        // The names on both sides of that matching are fixed the moment this
+        // site is compiled, but the VM was redoing it on every call, twice:
+        // buildBoundArgs linear-scanned a name-keyed BoundArgs (copying each
+        // name into it), then bindBoundArgsIntoFrame linear-scanned it again
+        // for every parameter, then a third nested loop compared every bound
+        // name against every parameter name. A two-argument call did roughly
+        // ten std::string comparisons and two string copies to reach an
+        // answer that was already known. Binding straight into the frame's
+        // slots also MOVES each argument instead of moving it into BoundArgs
+        // and copying it back out.
+        struct ArgBind {
+            int paramIndex = -1;    // >=0: this argument binds that parameter
+            // Any FURTHER parameters of the same name. Normally empty, but a
+            // declaration may repeat a parameter name -- BOSL2's
+            // regular_prism() declares both `length` and `height` twice --
+            // and the name-matching path this replaced bound every one of
+            // them, because it walked the parameter list asking "is there a
+            // bound argument called this?" rather than the other way round.
+            // Binding only the first silently left the body reading undef
+            // from whichever slot the duplicate name finally resolved to.
+            std::vector<int> alsoParams;
+            bool toDyn = false;     // instead bind by name into ctx.dyn ($-named, undeclared)
+            bool warnUnexpectedNamed = false;
+            bool warnTooManyPositional = false;
+        };
+        std::vector<ArgBind> argBinds;
+        bool hasArgPlan = false; // argBinds is authoritative (it is empty for a zero-argument call too)
     };
 
     // An upvalue read (see Op::LoadUpvalue): `targetDecl` is the enclosing

{openscad_cpp_evaluator-1.6.1 → openscad_cpp_evaluator-1.7.2}/include/openscad_cpp_evaluator/function_builtins.hpp

@@ -26,8 +26,35 @@ bool isBuiltinFunctionName(const std::string& name);
 // accept $-prefixed named-argument overrides). Mirrors the reference's
 // _math_fns dispatch table plus the textmetrics()/fontmetrics() special
 // cases (implemented on top of FontProvider, text_metrics.hpp).
+// One id per name evalBuiltinFunction handles (NOT the same list as
+// isBuiltinFunctionName -- "object" is deliberately absent, since it is
+// special-cased to builtinObject() before this function is reached). Public
+// so a CALL SITE can resolve its callee once, at compile time
+// (CompiledChunk::CallSite::builtinId), instead of hashing the name string
+// on every single call.
+enum class BuiltinFnId {
+    None, // not a name evalBuiltinFunction handles
+    TextMetrics, FontMetrics, Abs, Sign, Ceil, Floor, Round, Sqrt, Ln, Log, Exp, Sin, Cos, Tan,
+    Asin, Acos, Atan, Atan2, Max, Min, Pow, Norm, Cross, Rands, Concat, Len, Str, Chr, Ord,
+    IsUndef, IsNum, IsBool, IsString, IsList, IsFunction, IsObject, Search, Lookup, HasKey,
+    Version, VersionNum, ParentModule, DxfDim, DxfCross, SupportedFeature, LinearSolve,
+};
+
+// `name` -> its id, or None. The one place that hashes the name; everything
+// on a hot path should call this once at compile time and keep the answer.
+BuiltinFnId builtinFnIdFor(const std::string& name);
+
 Value evalBuiltinFunction(Evaluator& ev, const std::string& name, const CallArgs& args, const oscad::ASTNode& node);
 
+// The same dispatch with both of its name lookups already done: `id` from
+// builtinFnIdFor and `declaredParams` from builtinParamNames (dispatch.hpp),
+// which for all but a couple of builtins is null. `name` survives only
+// because diagnostics quote it. The string-taking overload above is just
+// this one with the two lookups performed first, and remains the entry point
+// for the AST interpreter, where there is no call site to cache them on.
+Value evalBuiltinFunctionResolved(Evaluator& ev, BuiltinFnId id, const std::vector<std::string>* declaredParams,
+                                   const std::string& name, const CallArgs& args, const oscad::ASTNode& node);
+
 // object(a=1, b=2, ...) -- an ordered string-keyed map merging positional
 // (an existing object's entries, or a list of [key,value] pairs) and named
 // arguments, later arguments winning over earlier ones for the same key --

{openscad_cpp_evaluator-1.6.1 → openscad_cpp_evaluator-1.7.2}/pyproject.toml

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

{openscad_cpp_evaluator-1.6.1 → openscad_cpp_evaluator-1.7.2}/src/builtins/function_builtins.cpp

@@ -1007,12 +1007,7 @@ namespace {
 // `if (name == "...")` string-compare chain; the switch below then
 // compiles to a jump table instead of sequential comparisons. No branch's
 // logic changed, only how it's reached.
-enum class BuiltinFnId {
-    TextMetrics, FontMetrics, Abs, Sign, Ceil, Floor, Round, Sqrt, Ln, Log, Exp, Sin, Cos, Tan,
-    Asin, Acos, Atan, Atan2, Max, Min, Pow, Norm, Cross, Rands, Concat, Len, Str, Chr, Ord,
-    IsUndef, IsNum, IsBool, IsString, IsList, IsFunction, IsObject, Search, Lookup, HasKey,
-    Version, VersionNum, ParentModule, DxfDim, DxfCross, SupportedFeature, LinearSolve,
-};
+// BuiltinFnId itself now lives in function_builtins.hpp -- see builtinFnIdFor.
 
 // supported_feature("name") -> the level at which this build implements that
 // feature, or 0 for one it does not implement (and for a name it has never
@@ -1242,18 +1237,26 @@ bool checkBuiltinArgs(Evaluator& ev, const std::string& name, BuiltinFnId id, co
 
 } // namespace
 
+BuiltinFnId builtinFnIdFor(const std::string& name) {
+    const auto& ids = builtinFnIds();
+    const auto it = ids.find(name);
+    return it == ids.end() ? BuiltinFnId::None : it->second;
+}
+
 Value evalBuiltinFunction(Evaluator& ev, const std::string& name, const CallArgs& args, const oscad::ASTNode& node) {
+    return evalBuiltinFunctionResolved(ev, builtinFnIdFor(name), builtinParamNames(name), name, args, node);
+}
 
-    const auto& ids = builtinFnIds();
-    const auto idIt = ids.find(name);
+Value evalBuiltinFunctionResolved(Evaluator& ev, BuiltinFnId id, const std::vector<std::string>* declaredParams,
+                                   const std::string& name, const CallArgs& args, const oscad::ASTNode& node) {
     // Not one of the names this function handles (e.g. "object", routed
     // elsewhere before reaching here) -- mirrors the old chain's fallthrough.
-    if (idIt == ids.end()) return Value{};
+    if (id == BuiltinFnId::None) return Value{};
 
     // Only textmetrics/fontmetrics have an entry -- every other builtin
     // function reads its arguments positionally upstream and warns about
     // nothing. See builtinParamNames (registry.cpp).
-    if (const std::vector<std::string>* declared = builtinParamNames(name)) {
+    if (const std::vector<std::string>* declared = declaredParams) {
         for (const auto& [argName, _] : args.named) {
             if (!isConfigVariable(argName) &&
                 std::find(declared->begin(), declared->end(), argName) == declared->end()) {
@@ -1265,9 +1268,10 @@ Value evalBuiltinFunction(Evaluator& ev, const std::string& name, const CallArgs
     // Arity and argument types, with the reference's own two diagnostics.
     // This replaced a silent version of the same gate (scalarNumericArity /
     // numericOnlyNames), which returned undef without ever saying why.
-    if (!checkBuiltinArgs(ev, name, idIt->second, args, &node.position())) return Value{};
+    if (!checkBuiltinArgs(ev, name, id, args, &node.position())) return Value{};
 
-    switch (idIt->second) {
+    switch (id) {
+        case BuiltinFnId::None: return Value{}; // unreachable: handled above
         case BuiltinFnId::TextMetrics: return builtinTextmetrics(ev, args);
         case BuiltinFnId::FontMetrics: return builtinFontmetrics(ev, args);
         case BuiltinFnId::Abs: return Value{std::fabs(toDoubleLenient(getArg(args, 0, "x", Value{})))};

{openscad_cpp_evaluator-1.6.1 → openscad_cpp_evaluator-1.7.2}/src/bytecode_compiler.cpp

@@ -20,6 +20,59 @@
 namespace oscadeval {
 
 namespace {
+// Records every parameter called `name`, not just the first. See
+// CompiledChunk::CallSite::ArgBind::alsoParams for why there can be more
+// than one.
+void bindEveryParamNamed(CompiledChunk::CallSite::ArgBind& b,
+                         const std::vector<std::unique_ptr<oscad::ParameterDeclaration>>& params,
+                         const std::string& name) {
+    for (size_t p = 0; p < params.size(); ++p) {
+        if (params[p]->name->name != name) continue;
+        if (b.paramIndex < 0) {
+            b.paramIndex = static_cast<int>(p);
+        } else {
+            b.alsoParams.push_back(static_cast<int>(p));
+        }
+    }
+}
+
+// Replays buildBoundArgs' own positional/named matching rule (bytecode_vm.cpp)
+// against a parameter list known at compile time, recording the answer per
+// argument instead of recomputing it per call. The rule, unchanged: a named
+// argument binds the parameter of that name, warning when there is none and
+// the name is not a $-config variable; a positional argument binds the
+// parameter at its own positional index, warning once when it runs past the
+// end; an undeclared $-name still reaches ctx.dyn; anything else is dropped.
+// A later argument writing the same parameter still wins, because both bind
+// the same slot in order.
+void planCallSiteArgs(CompiledChunk::CallSite& site,
+                      const std::vector<std::unique_ptr<oscad::ParameterDeclaration>>& params) {
+    const size_t nparams = params.size();
+    size_t positionalIdx = 0;
+    site.argBinds.resize(site.argNames.size());
+    for (size_t i = 0; i < site.argNames.size(); ++i) {
+        CompiledChunk::CallSite::ArgBind& b = site.argBinds[i];
+        if (site.argNames[i]) {
+            const std::string& name = *site.argNames[i];
+            bindEveryParamNamed(b, params, name);
+            const bool found = b.paramIndex >= 0;
+            b.warnUnexpectedNamed = !found && !isConfigVariable(name);
+            b.toDyn = !found && !name.empty() && name[0] == '$';
+        } else {
+            if (positionalIdx < nparams) {
+                // By NAME, not just by index: a positional argument landing on
+                // a repeated name filled every parameter of that name too,
+                // because the old path keyed its bound arguments by name.
+                bindEveryParamNamed(b, params, params[positionalIdx]->name->name);
+            } else if (positionalIdx == nparams) {
+                b.warnTooManyPositional = true;
+            }
+            ++positionalIdx;
+        }
+    }
+    site.hasArgPlan = true;
+}
+
 
 // Thrown by compileExpr wherever it hits a construct this phase doesn't
 // compile yet -- tryCompileFunction catches it and returns nullopt (falls
@@ -601,6 +654,11 @@ public:
                         // call-site interleaved order, not resolveArgs'
                         // split positional/named CallArgs shape).
                         site.isBuiltin = true;
+                        // Resolve the callee here rather than per call; see
+                        // CallSite's own doc comment (bytecode.hpp).
+                        site.builtinId = builtinFnIdFor(calleeName);
+                        site.declaredParams = builtinParamNames(calleeName);
+                        site.isObjectBuiltin = (calleeName == "object");
                         isStatic = true;
                     }
                     // Anything else stays dynamic: a function-literal value,
@@ -674,6 +732,9 @@ public:
                         }
                     }
                 }
+                // Resolve every argument to its parameter now; see
+                // CallSite::argBinds (bytecode.hpp) for why.
+                if (site.decl) planCallSiteArgs(site, site.decl->parameters);
                 int siteIdx = static_cast<int>(chunk_.callSites.size());
                 chunk_.callSites.push_back(std::move(site));
                 // Builtins and import() never trampoline (matching

{openscad_cpp_evaluator-1.6.1 → openscad_cpp_evaluator-1.7.2}/src/bytecode_vm.cpp

@@ -49,8 +49,12 @@ CallArgs& buildCallArgs(const CompiledChunk::CallSite& site, Value* args, size_t
 // LIST is `paramNames` (in declared order -- a FunctionDeclaration's
 // parameters or a FunctionLiteral's). Shared by CallFn/CallFnTail (a
 // site.decl callee) and CallDynamic/CallDynamicTail (a closure callee).
+// `emitWarnings=false` is for the one caller that has already emitted them
+// through warnPlannedArgs and only needs the binding -- see Op::CallFnTail's
+// no-hop fallback.
 BoundArgs buildBoundArgs(Evaluator& ev, const CompiledChunk::CallSite& site, Value* args, size_t argCount,
-                          const std::vector<std::unique_ptr<oscad::ParameterDeclaration>>& paramNames) {
+                          const std::vector<std::unique_ptr<oscad::ParameterDeclaration>>& paramNames,
+                          bool emitWarnings = true) {
     BoundArgs bound;
     bound.reserve(argCount);
     size_t positionalIdx = 0;
@@ -59,14 +63,14 @@ BoundArgs buildBoundArgs(Evaluator& ev, const CompiledChunk::CallSite& site, Val
     for (size_t i = 0; i < argCount; ++i) {
         if (site.argNames[i]) {
             const std::string& name = *site.argNames[i];
-            if (!isConfigVariable(name) && !declaresParam(paramNames, name)) {
+            if (emitWarnings && !isConfigVariable(name) && !declaresParam(paramNames, name)) {
                 warnUnexpectedNamedArg(ev, name, pos);
             }
             bound.set(name, std::move(args[i]));
         } else {
             if (positionalIdx < nparams) {
                 bound.set(paramNames[positionalIdx]->name->name, std::move(args[i]));
-            } else if (positionalIdx == nparams) {
+            } else if (emitWarnings && positionalIdx == nparams) {
                 warnTooManyPositionalArgs(ev, pos);
             }
             ++positionalIdx;
@@ -108,6 +112,71 @@ void bindBoundArgsIntoFrame(const CompiledChunk& chunk, const BoundArgs& bound,
     }
 }
 
+// Where a pushed frame's arguments come from: a call site's compile-time plan
+// over the caller's own live operand stack (the hot path), or an
+// already-name-matched BoundArgs (closures and dynamic callees, which have no
+// compile-time parameter list to plan against).
+struct FrameArgs {
+    const CompiledChunk::CallSite* site = nullptr;
+    Value* args = nullptr;
+    size_t argCount = 0;
+    const BoundArgs* bound = nullptr;
+};
+
+// The compile-time counterpart of bindBoundArgsIntoFrame: binds a call's
+// arguments straight from the caller's operand stack into the callee frame,
+// using the plan its call site worked out once (CallSite::argBinds). No name
+// is compared and no BoundArgs is built, and each argument is MOVED into its
+// slot rather than moved into a BoundArgs and copied back out. `args` must
+// still be live -- the caller truncates its stack only after this returns.
+// The argument diagnostics of a planned call, split out of the binder below
+// because WHEN they fire is observable: their "TRACE: called by ..." line
+// names whatever is on top of the call stack, and a tail hop has already
+// replaced that with the CALLEE by the time it binds. buildBoundArgs warned
+// before any of that happened, so this must too -- caught by
+// UnexpectedArgs.NestedUserFunctionCallStillWarns, which compares the VM
+// against the interpreter.
+void warnPlannedArgs(Evaluator& ev, const CompiledChunk::CallSite& site, size_t argCount) {
+    const oscad::Position* pos = site.callNode ? &site.callNode->position() : nullptr;
+    for (size_t i = 0; i < argCount; ++i) {
+        const CompiledChunk::CallSite::ArgBind& b = site.argBinds[i];
+        if (b.warnUnexpectedNamed) warnUnexpectedNamedArg(ev, *site.argNames[i], pos);
+        if (b.warnTooManyPositional) warnTooManyPositionalArgs(ev, pos);
+    }
+}
+
+void bindPlannedArgsIntoFrame(const CompiledChunk& chunk, const CompiledChunk::CallSite& site, Value* args,
+                              size_t argCount, VmFrame& frame) {
+    EvalContext& ctx = frame.ctxChain.back();
+    for (size_t i = 0; i < argCount; ++i) {
+        const CompiledChunk::CallSite::ArgBind& b = site.argBinds[i];
+        if (b.paramIndex >= 0) {
+            // The duplicate-name case (alsoParams) needs the value more than
+            // once, so it is copied there and only the last one moves.
+            for (const int extra : b.alsoParams) {
+                const CompiledChunk::Param& e = chunk.params[static_cast<size_t>(extra)];
+                if (e.isDyn) {
+                    ctx.dyn->set(e.name, args[i]);
+                } else {
+                    frame.slots[static_cast<size_t>(e.slot)] = args[i];
+                }
+                frame.bound[static_cast<size_t>(extra)] = true;
+            }
+            const CompiledChunk::Param& p = chunk.params[static_cast<size_t>(b.paramIndex)];
+            if (p.isDyn) {
+                ctx.dyn->set(p.name, std::move(args[i]));
+            } else {
+                frame.slots[static_cast<size_t>(p.slot)] = std::move(args[i]);
+            }
+            frame.bound[static_cast<size_t>(b.paramIndex)] = true;
+        } else if (b.toDyn) {
+            ctx.dyn->set(*site.argNames[i], std::move(args[i]));
+        }
+        // else: an undeclared plain name, or a positional past the end --
+        // dropped, exactly as the name-matching path drops it.
+    }
+}
+
 // Same, but for a call site whose arguments are still raw AST (evaluated
 // here against `callerCtx`) -- only ever used by runCompiledFunction's own
 // entry point (a top-level call with raw AST arguments, mirroring
@@ -249,7 +318,7 @@ void pushBareFrame(Evaluator& ev, const CompiledChunk& chunk, const std::vector<
 // own parameters exactly (a FunctionDeclaration's decl/*decl.expr, or a
 // FunctionLiteral's funcNode/*funcNode.body).
 void pushBracketedCallFrame(Evaluator& ev, const CompiledChunk& chunk, const oscad::ASTNode& declNode,
-                             const oscad::Expression& bodyExpr, const std::string& name, BoundArgs bound,
+                             const oscad::Expression& bodyExpr, const std::string& name, const FrameArgs& fargs,
                              EvalContext& callerCtx, const oscad::Scope* fnScope,
                              const std::shared_ptr<TrailView<Value>>& capturedLet, const oscad::Position* callPos) {
     if (ev.vmCallStack_.size() >= Evaluator::kMaxVmCallStackDepth) {
@@ -274,7 +343,11 @@ void pushBracketedCallFrame(Evaluator& ev, const CompiledChunk& chunk, const osc
     frame->tailHopGuard = 0;
     frame->logicalName = name;
     frame->hopEligible = true; // just pushed a fresh, correctly-named callStack_ entry
-    bindBoundArgsIntoFrame(chunk, bound, *frame);
+    if (fargs.site) {
+        bindPlannedArgsIntoFrame(chunk, *fargs.site, fargs.args, fargs.argCount, *frame);
+    } else {
+        bindBoundArgsIntoFrame(chunk, *fargs.bound, *frame);
+    }
     applyCompiledDefaultsToFrame(ev, chunk, *frame);
 
     // enterUserCall's own bodyCtx must point at frame->ctxChain's OWN
@@ -802,7 +875,7 @@ Value driveVm(Evaluator& ev, size_t floor) {
                         f.stack.resize(argBase);
                         f.stack.push_back(importAsValue(ev, callArgs, *site.callNode));
                         ++f.pc;
-                    } else if (site.isBuiltin && site.calleeName == "object") {
+                    } else if (site.isObjectBuiltin) {
                         std::vector<std::pair<std::optional<std::string>, Value>> pairs;
                         pairs.reserve(argCount);
                         for (size_t i = 0; i < argCount; ++i) pairs.emplace_back(site.argNames[i], std::move(args[i]));
@@ -812,24 +885,39 @@ Value driveVm(Evaluator& ev, size_t floor) {
                     } else if (site.isBuiltin) {
                         CallArgs& callArgs = buildCallArgs(site, args, argCount, f.argScratch);
                         f.stack.resize(argBase);
-                        f.stack.push_back(evalBuiltinFunction(ev, site.calleeName, callArgs, *site.callNode));
+                        f.stack.push_back(evalBuiltinFunctionResolved(ev, site.builtinId, site.declaredParams,
+                                                                      site.calleeName, callArgs, *site.callNode));
                         ++f.pc;
                     } else {
-                        BoundArgs bound = buildBoundArgs(ev, site, args, argCount, site.decl->parameters);
-                        f.stack.resize(argBase);
                         const CompiledChunk* calleeChunk = ev.useBytecodeVm() ? ev.lookupOrCompileChunk(*site.decl) : nullptr;
-                        if (calleeChunk) {
+                        if (calleeChunk && site.hasArgPlan) {
+                            warnPlannedArgs(ev, site, argCount);
+                            // The hot path: bind straight off this frame's own
+                            // stack using the site's compile-time plan, then
+                            // truncate. Truncating FIRST would destroy the very
+                            // values being bound.
                             const oscad::Scope* fnScope = ctx.scopeOf(*site.decl) ? ctx.scopeOf(*site.decl) : ctx.scope;
                             pushBracketedCallFrame(ev, *calleeChunk, *site.decl, *site.decl->expr, site.calleeName,
-                                                    std::move(bound), ctx, fnScope, nullptr, &site.callNode->position());
+                                                    FrameArgs{&site, args, argCount, nullptr}, ctx, fnScope, nullptr,
+                                                    &site.callNode->position());
+                            f.stack.resize(argBase);
                             // f.pc deliberately NOT advanced -- resumes when the
                             // pushed frame completes (see driveVm's own
                             // completion branch, above).
                         } else {
-                            Value result = ev.evalUserFunctionFromBound(site.calleeName, *site.decl, std::move(bound), ctx,
-                                                                          &site.callNode->position());
-                            f.stack.push_back(std::move(result));
-                            ++f.pc;
+                            BoundArgs bound = buildBoundArgs(ev, site, args, argCount, site.decl->parameters);
+                            f.stack.resize(argBase);
+                            if (calleeChunk) {
+                                const oscad::Scope* fnScope = ctx.scopeOf(*site.decl) ? ctx.scopeOf(*site.decl) : ctx.scope;
+                                pushBracketedCallFrame(ev, *calleeChunk, *site.decl, *site.decl->expr, site.calleeName,
+                                                        FrameArgs{nullptr, nullptr, 0, &bound}, ctx, fnScope, nullptr,
+                                                        &site.callNode->position());
+                            } else {
+                                Value result = ev.evalUserFunctionFromBound(site.calleeName, *site.decl, std::move(bound),
+                                                                              ctx, &site.callNode->position());
+                                f.stack.push_back(std::move(result));
+                                ++f.pc;
+                            }
                         }
                     }
                     break;
@@ -849,7 +937,7 @@ Value driveVm(Evaluator& ev, size_t floor) {
                         if (calleeChunk) {
                             const oscad::Scope* fnScope = ctx.scopeOf(funcNode) ? ctx.scopeOf(funcNode) : ctx.scope;
                             pushBracketedCallFrame(ev, *calleeChunk, funcNode, *funcNode.body, "<function literal>",
-                                                    std::move(bound), ctx, fnScope, capturedLetTrail(closure), ins.pos);
+                                                    FrameArgs{nullptr, nullptr, 0, &bound}, ctx, fnScope, capturedLetTrail(closure), ins.pos);
                         } else {
                             Value result = ev.evalFunctionLiteralFromBound(closure, std::move(bound), ctx, ins.pos);
                             f.stack.push_back(std::move(result));
@@ -868,8 +956,17 @@ Value driveVm(Evaluator& ev, size_t floor) {
                     const size_t argCount = static_cast<size_t>(ins.b);
                     const size_t argBase = f.stack.size() - argCount;
                     Value* args = f.stack.data() + argBase; // into f.stack; truncated below once consumed
-                    BoundArgs bound = buildBoundArgs(ev, site, args, argCount, site.decl->parameters);
-                    f.stack.resize(argBase);
+                    // A planned site defers both of these: the arguments have
+                    // to stay live on this frame's own stack until they are
+                    // bound, and a tail HOP binds into this very frame.
+                    const bool planned = site.hasArgPlan;
+                    BoundArgs bound;
+                    if (planned) {
+                        warnPlannedArgs(ev, site, argCount); // before recordTailCallHop; see warnPlannedArgs
+                    } else {
+                        bound = buildBoundArgs(ev, site, args, argCount, site.decl->parameters);
+                        f.stack.resize(argBase);
+                    }
                     // Tail-hop-in-place requires f.hopEligible -- a frame
                     // that's call-boundary-free (statement expression,
                     // assignment block, parameter default) has no
@@ -898,22 +995,37 @@ Value driveVm(Evaluator& ev, size_t floor) {
                         f.setCode(calleeChunk->bodyCode);
                         f.pc = 0;
                         f.slots.assign(static_cast<size_t>(calleeChunk->numSlots), Value{});
-                        f.stack.clear();
                         f.bound.assign(calleeChunk->params.size(), false);
                         f.accumStack.clear();
                         f.iterLists.assign(static_cast<size_t>(calleeChunk->numIterLists), IterList{});
                         f.ctxChain.push_back(std::move(*hopCtx));
-                        bindBoundArgsIntoFrame(*calleeChunk, bound, f);
+                        // The stack is cleared AFTER binding on the planned
+                        // path: a hop rebinds this same frame, and `args`
+                        // still points into the stack it would have wiped.
+                        if (planned) {
+                            bindPlannedArgsIntoFrame(*calleeChunk, site, args, argCount, f);
+                            f.stack.clear();
+                        } else {
+                            f.stack.clear();
+                            bindBoundArgsIntoFrame(*calleeChunk, bound, f);
+                        }
                         applyCompiledDefaultsToFrame(ev, *calleeChunk, f);
                         // continue via the outer while -- re-fetches this
                         // same (now-mutated) frame from its new pc=0.
                     } else {
+                        if (planned) { // no hop after all -- fall back to name matching
+                            // warnPlannedArgs already emitted these above.
+                            bound = buildBoundArgs(ev, site, args, argCount, site.decl->parameters,
+                                                    /*emitWarnings=*/false);
+                            f.stack.resize(argBase);
+                        }
                         const CompiledChunk* fallbackChunk =
                             ev.useBytecodeVm() ? ev.lookupOrCompileChunk(*site.decl) : nullptr;
                         if (fallbackChunk) {
                             const oscad::Scope* fnScope = ctx.scopeOf(*site.decl) ? ctx.scopeOf(*site.decl) : ctx.scope;
                             pushBracketedCallFrame(ev, *fallbackChunk, *site.decl, *site.decl->expr, site.calleeName,
-                                                    std::move(bound), ctx, fnScope, nullptr, &site.callNode->position());
+                                                    FrameArgs{nullptr, nullptr, 0, &bound}, ctx, fnScope, nullptr,
+                                                    &site.callNode->position());
                         } else {
                             Value result = ev.evalUserFunctionFromBound(site.calleeName, *site.decl, std::move(bound), ctx,
                                                                           &site.callNode->position());
@@ -960,7 +1072,7 @@ Value driveVm(Evaluator& ev, size_t floor) {
                             if (fallbackChunk) {
                                 const oscad::Scope* fnScope = ctx.scopeOf(funcNode) ? ctx.scopeOf(funcNode) : ctx.scope;
                                 pushBracketedCallFrame(ev, *fallbackChunk, funcNode, *funcNode.body, "<function literal>",
-                                                        std::move(bound), ctx, fnScope, capturedLetTrail(closure), ins.pos);
+                                                        FrameArgs{nullptr, nullptr, 0, &bound}, ctx, fnScope, capturedLetTrail(closure), ins.pos);
                             } else {
                                 Value result = ev.evalFunctionLiteralFromBound(closure, std::move(bound), ctx, ins.pos);
                                 f.stack.push_back(std::move(result));