openscad-cpp-evaluator 0.46.0__tar.gz → 0.48.0__tar.gz

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/CLAUDE.md

@@ -45,9 +45,13 @@ comprehension clause kinds, user function calls (recursion, defaults, `FunctionL
 user module calls (`children()`/`children(N)`, closure detection via `callCtxFor`), list
 indexing/swizzle member access; the full math/string/list/type-check builtin *function* dispatch
 (`sin`/`cos`/`pow`/`search`/`lookup`/`chr`/`ord`/`is_*`/`object`/`has_key`/etc, ~43 names — a
-completely separate namespace/precedence rule from the builtin *modules* in `registry.cpp`: a
-builtin function name always wins over a same-named user function, checked *before* the
-user-function lookup), STL/OBJ/OFF/3MF `import()` in both module (geometry) and expression
+same precedence rule as the builtin *modules* in `registry.cpp`: a user-defined function
+**shadows** a same-named builtin, looked up *before* the builtin table. This was backwards until
+0.47.0 — the port copied the old Python evaluator's `_eval_function_call` order, which had it
+wrong; OpenSCAD 2026.02.01 echoes 999 for `function abs(x)=999; abs(-3)` and we echoed 3. Fixing
+it needs **both** resolution sites: `evalFunctionCall` (`user_calls.cpp`) and the compiler's
+call-site resolution (`bytecode_compiler.cpp`), which bakes builtin-vs-user in at compile time,
+plus gating the silent `is_undef` probe on the call actually resolving to the builtin), STL/OBJ/OFF/3MF `import()` in both module (geometry) and expression
 (VNF/JSON) contexts, and 3MF read/write; (Phase 6) `hull()`/`minkowski()` (transparent-splice
 CSG-tree shape like union/difference/intersection, role-split via the shared `splitByRole`),
 `linear_extrude()`/`rotate_extrude()`/`projection(cut=)`, and `roof()`; and (Phase 7) `offset()`,
@@ -456,6 +460,20 @@ grep for `ponytail:`.
   unknown arguments -- `children(separate=true)` renders the wrong shape there with no warning --
   and both read as `undef` in OpenSCAD, so a guard written against them works in both.
 
+- **`matrix_solve(A, b)`** (`src/builtins/function_builtins.cpp`, feature name `matrix-solve`) —
+  one pivoted LU answering three questions from the same factorisation: `.x` (solution; a vector
+  for a vector `b`, a matrix for a matrix `b`, `undef` when `b` is omitted), `.det`, `.singular`.
+  Square systems only — BOSL2's `linear_solve` also does least-squares/minimum-norm via QR, which
+  LU cannot, and those paths are already fast in script. A non-square or non-numeric matrix warns
+  and returns `undef`; a **singular** one is reported (`singular=true`, `det=0`, `x=undef`), not
+  warned about, because asking whether a matrix is singular is a fair question.
+  Why it exists: BOSL2's `determinant()` is a cofactor expansion, O(n!) in time *and* in
+  intermediate list allocation. Measured through the CLI on identical matrices, with identical
+  results: **n=10 3.17s → 0.33s, n=11 31.49s → 0.33s**. Its `linear_solve` is not the problem
+  (128×128 in ~0.18s since its Apr 2026 Householder rewrite) — but its singularity test is a fixed
+  **absolute** `1e-9` on R's diagonal with no scaling by ‖A‖, so `2*I` scaled by 1e-10 is declared
+  singular there and solves correctly here. This one uses a relative threshold.
+
 - `include/openscad_cpp_evaluator/value.hpp`, `src/value.cpp` — the `Value` variant (OpenSCAD's
   dynamic value type) and its free-function arithmetic/comparison helpers. See the plan's §1 for
   the type-mapping table and why there's no numpy-equivalent library.

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/PKG-INFO

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

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/pyproject.toml

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

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/src/builtins/function_builtins.cpp

@@ -169,6 +169,172 @@ Value builtinCross(const Value& aArg, const Value& bArg) {
     return Value{};
 }
 
+// -- matrix_solve(A, b) --------------------------------------------------
+//
+// One pivoted LU answers three questions at once -- the solution, the
+// determinant, and whether A is singular -- because all three fall out of
+// the same factorisation.
+//
+// The motivation is BOSL2's determinant() (linalg.scad), a cofactor
+// expansion: O(n!) time AND O(n!) intermediate list allocation. Measured
+// through this evaluator: 0.04s at n=8, 0.38s at n=9, 2.7s at n=10, and
+// projecting to minutes at n=12. This is O(n^3). BOSL2's linear_solve, by
+// contrast, was already fast (128x128 in ~0.18s after its Apr 2026
+// Householder rewrite), so speed is not the argument for the solve half --
+// a correct singularity test is. See below.
+//
+// Square systems only. BOSL2's linear_solve also handles overdetermined
+// (least-squares) and underdetermined (minimum-norm) systems via QR; LU
+// cannot, and those paths are quick enough in script. A non-square matrix
+// warns rather than silently doing something else.
+
+// Defined further down, next to the other object() helpers.
+Value objectOf(std::vector<std::pair<std::string, Value>> items);
+
+// A rectangular numeric matrix as (row-major values, column count).
+// nullopt for anything that is not a non-empty list of equal-length,
+// non-empty numeric lists.
+std::optional<std::pair<std::vector<double>, size_t>> numericMatrix(const Value& v) {
+    const ListPtr* rows = std::get_if<ListPtr>(&v);
+    if (!rows || !*rows || (*rows)->items.empty()) return std::nullopt;
+    std::vector<double> flat;
+    size_t cols = 0;
+    for (size_t r = 0; r < (*rows)->items.size(); ++r) {
+        const std::optional<std::vector<double>> row = allNumericList((*rows)->items[r]);
+        if (!row || row->empty()) return std::nullopt;
+        if (r == 0) {
+            cols = row->size();
+        } else if (row->size() != cols) {
+            return std::nullopt;
+        }
+        flat.insert(flat.end(), row->begin(), row->end());
+    }
+    return std::make_pair(std::move(flat), cols);
+}
+
+Value builtinMatrixSolve(Evaluator& ev, const Value& aArg, const Value& bArg, bool haveB,
+                          const oscad::ASTNode& node) {
+    const auto parsed = numericMatrix(aArg);
+    if (!parsed) {
+        ev.warn("matrix_solve() requires a matrix of numbers", &node.position());
+        return Value{};
+    }
+    std::vector<double> lu = parsed->first;
+    const size_t cols = parsed->second;
+    const size_t n = lu.size() / cols;
+    if (n != cols) {
+        ev.warn("matrix_solve() requires a square matrix, found " + std::to_string(n) + " x " +
+                    std::to_string(cols),
+                &node.position());
+        return Value{};
+    }
+    double maxAbs = 0.0;
+    for (double x : lu) {
+        if (!std::isfinite(x)) {
+            ev.warn("matrix_solve() matrix contains a non-finite value", &node.position());
+            return Value{};
+        }
+        maxAbs = std::max(maxAbs, std::abs(x));
+    }
+
+    // Right-hand side: a vector of n is one column; a matrix of n rows is
+    // one column per column. Kept row-major alongside the factorisation.
+    size_t k = 0;
+    bool bWasVector = false;
+    std::vector<double> rhs;
+    if (haveB) {
+        if (const std::optional<std::vector<double>> vec = allNumericList(bArg); vec && vec->size() == n) {
+            bWasVector = true;
+            k = 1;
+            rhs = *vec;
+        } else if (const auto bm = numericMatrix(bArg); bm && bm->first.size() / bm->second == n) {
+            k = bm->second;
+            rhs = bm->first;
+        } else {
+            ev.warn("matrix_solve() right-hand side must be a vector of " + std::to_string(n) +
+                        " numbers, or a matrix with that many rows",
+                    &node.position());
+            return Value{};
+        }
+        for (double x : rhs) {
+            if (!std::isfinite(x)) {
+                ev.warn("matrix_solve() right-hand side contains a non-finite value", &node.position());
+                return Value{};
+            }
+        }
+    }
+
+    // Relative singularity threshold. BOSL2 compares R's diagonal against a
+    // fixed ABSOLUTE 1e-9 (its _EPSILON) with no scaling by the size of the
+    // matrix, so a perfectly well-conditioned system scaled down by 1e-10
+    // is declared singular there. Scaling by maxAbs is what makes
+    // matrix_solve(A*1e-10) still solvable.
+    const double tol = std::numeric_limits<double>::epsilon() * static_cast<double>(n) * std::max(maxAbs, 1.0);
+
+    double det = 1.0;
+    bool singular = false;
+    for (size_t col = 0; col < n && !singular; ++col) {
+        size_t pivot = col;
+        for (size_t r = col + 1; r < n; ++r) {
+            if (std::abs(lu[r * n + col]) > std::abs(lu[pivot * n + col])) pivot = r;
+        }
+        if (std::abs(lu[pivot * n + col]) <= tol) {
+            singular = true;
+            break;
+        }
+        if (pivot != col) {
+            for (size_t c = 0; c < n; ++c) std::swap(lu[col * n + c], lu[pivot * n + c]);
+            for (size_t c = 0; c < k; ++c) std::swap(rhs[col * k + c], rhs[pivot * k + c]);
+            det = -det;
+        }
+        const double p = lu[col * n + col];
+        det *= p;
+        for (size_t r = col + 1; r < n; ++r) {
+            const double f = lu[r * n + col] / p;
+            if (f == 0.0) continue;
+            lu[r * n + col] = 0.0;
+            for (size_t c = col + 1; c < n; ++c) lu[r * n + c] -= f * lu[col * n + c];
+            for (size_t c = 0; c < k; ++c) rhs[r * k + c] -= f * rhs[col * k + c];
+        }
+    }
+
+    std::vector<std::pair<std::string, Value>> out;
+    if (singular) {
+        // Not a misuse -- "is this matrix singular?" is a legitimate
+        // question to ask matrix_solve, so it answers rather than warning.
+        out.emplace_back("x", Value{});
+        out.emplace_back("det", Value{0.0});
+        out.emplace_back("singular", Value{true});
+        return objectOf(std::move(out));
+    }
+
+    if (haveB) {
+        for (size_t col = n; col-- > 0;) {
+            for (size_t c = 0; c < k; ++c) {
+                double acc = rhs[col * k + c];
+                for (size_t j = col + 1; j < n; ++j) acc -= lu[col * n + j] * rhs[j * k + c];
+                rhs[col * k + c] = acc / lu[col * n + col];
+            }
+        }
+        if (bWasVector) {
+            out.emplace_back("x", numList(rhs));
+        } else {
+            std::vector<Value> rowsOut;
+            rowsOut.reserve(n);
+            for (size_t r = 0; r < n; ++r) {
+                rowsOut.push_back(numList(std::vector<double>(rhs.begin() + static_cast<long>(r * k),
+                                                               rhs.begin() + static_cast<long>((r + 1) * k))));
+            }
+            out.emplace_back("x", listOf(std::move(rowsOut)));
+        }
+    } else {
+        out.emplace_back("x", Value{});
+    }
+    out.emplace_back("det", Value{det});
+    out.emplace_back("singular", Value{false});
+    return objectOf(std::move(out));
+}
+
 Value builtinRands(double minv, double maxv, double nArg, const Value& seedArg) {
     // ponytail: doesn't reproduce Python's Mersenne-Twister bit-for-bit --
     // no script should depend on cross-language RNG equality, only on
@@ -450,6 +616,7 @@ bool isBuiltinFunctionName(const std::string& name) {
         "chr", "ord", "is_undef", "is_num", "is_bool", "is_string", "is_list", "is_function", "is_object",
         "search", "lookup", "has_key", "version", "version_num", "parent_module",
         "object", "textmetrics", "fontmetrics", "dxf_dim", "dxf_cross", "supported_feature",
+        "matrix_solve",
     };
     return names.count(name) > 0;
 }
@@ -591,7 +758,7 @@ 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,
+    Version, VersionNum, ParentModule, DxfDim, DxfCross, SupportedFeature, MatrixSolve,
 };
 
 // supported_feature("name") -> the level at which this build implements that
@@ -611,6 +778,7 @@ enum class BuiltinFnId {
 const std::unordered_map<std::string, double>& featureLevels() {
     static const std::unordered_map<std::string, double> levels = {
         {"render-expr", 1.0},        // render() in expression position
+        {"matrix-solve", 1.0},       // matrix_solve(A, b) -> {x, det, singular}
         {"polyhedron-vnf", 1.0},     // polyhedron(vnf) / polyhedron(object)
         {"separate-children", 1.0},  // children(..., separate=true)
         {"minkowski-diff", 1.0},     // minkowski_difference()
@@ -645,6 +813,7 @@ const std::unordered_map<std::string, BuiltinFnId>& builtinFnIds() {
         {"parent_module", BuiltinFnId::ParentModule},
         {"dxf_dim", BuiltinFnId::DxfDim}, {"dxf_cross", BuiltinFnId::DxfCross},
         {"supported_feature", BuiltinFnId::SupportedFeature},
+        {"matrix_solve", BuiltinFnId::MatrixSolve},
     };
     return ids;
 }
@@ -726,6 +895,7 @@ const std::unordered_map<int, BuiltinCheck>& builtinChecks() {
         add(BuiltinFnId::ParentModule, {0, 1, "1", {kNum}});
         add(BuiltinFnId::HasKey, {-1, -1, nullptr, {{TObj, "object"}, {TStr, "string"}}});
         add(BuiltinFnId::SupportedFeature, {1, 1, "1", {}});
+        add(BuiltinFnId::MatrixSolve, {1, 2, "1 or 2", {kVec}});
         for (BuiltinFnId id : {BuiltinFnId::IsUndef, BuiltinFnId::IsNum, BuiltinFnId::IsBool,
                                 BuiltinFnId::IsString, BuiltinFnId::IsList, BuiltinFnId::IsFunction,
                                 BuiltinFnId::IsObject}) {
@@ -1040,6 +1210,9 @@ Value evalBuiltinFunction(Evaluator& ev, const std::string& name, const CallArgs
         // The OpenSCAD release we track. version_num() is that same
         // year/month/day folded as y * 10000 + m * 100 + d, exactly like the
         // reference's own builtin_version_num (builtin_functions.cc).
+        case BuiltinFnId::MatrixSolve:
+            return builtinMatrixSolve(ev, getArg(args, 0, "A", Value{}), getArg(args, 1, "b", Value{}),
+                                       args.findPositional(1) != nullptr || args.findNamed("b") != nullptr, node);
         case BuiltinFnId::SupportedFeature: {
             const Value name = getArg(args, 0, "feature", Value{});
             const std::string* s = std::get_if<std::string>(&name);

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/src/bytecode_compiler.cpp

@@ -567,6 +567,19 @@ public:
                         // evalBuiltinFunction when isImport is set.
                         site.isImport = true;
                         isStatic = true;
+                    } else if (const oscad::ASTNode* userFn =
+                                   scope_ ? scope_->lookupFunction(calleeName) : nullptr;
+                               userFn && userFn->kind() == NodeKind::FunctionDeclaration) {
+                        // A user-defined function SHADOWS a same-named
+                        // builtin, so this lookup runs BEFORE the builtin
+                        // table -- the same reordering as
+                        // evalFunctionCall's (user_calls.cpp), and it has
+                        // to happen here too: this decision is baked in at
+                        // COMPILE time, so leaving the builtin test first
+                        // would keep the bug on the default engine no
+                        // matter what the interpreter does.
+                        site.decl = static_cast<const oscad::FunctionDeclaration*>(userFn);
+                        isStatic = true;
                     } else if (isBuiltinFunctionName(calleeName)) {
                         // object() is already in this table -- it gets
                         // isBuiltin=true here like any other builtin, and
@@ -578,13 +591,10 @@ public:
                         // split positional/named CallArgs shape).
                         site.isBuiltin = true;
                         isStatic = true;
-                    } else {
-                        const oscad::ASTNode* found = scope_ ? scope_->lookupFunction(calleeName) : nullptr;
-                        if (found && found->kind() == NodeKind::FunctionDeclaration) {
-                            site.decl = static_cast<const oscad::FunctionDeclaration*>(found);
-                            isStatic = true;
-                        }
                     }
+                    // Anything else stays dynamic: a function-literal value,
+                    // or a name that is simply unknown. Op::CallDynamic
+                    // resolves it (and warns) at runtime.
                 }
 
                 if (!isStatic) {
@@ -626,7 +636,17 @@ public:
                 // is_undef(name) probes rather than reads -- the same quiet
                 // load the interpreter uses (Evaluator::undefProbeTarget),
                 // so the two engines agree on which reads warn.
-                if (const oscad::Identifier* undefProbe = Evaluator::undefProbeTarget(n)) {
+                //
+                // Only when the call resolves to the BUILTIN, though. A
+                // user function named is_undef shadows it (site resolution
+                // above) and evaluates its argument the ordinary way,
+                // warnings included -- which is what OpenSCAD does. The
+                // interpreter gets this for free by testing the probe
+                // inside its builtin branch; here the two are separate, so
+                // the condition has to be spelled out.
+                const oscad::Identifier* undefProbe =
+                    site.isBuiltin ? Evaluator::undefProbeTarget(n) : nullptr;
+                if (undefProbe) {
                     compileIdentifierLoad(undefProbe->name, undefProbe->position(), out, scope,
                                           /*warnIfUndef=*/false);
                     site.argNames.push_back(std::nullopt);

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/src/user_calls.cpp

@@ -876,11 +876,32 @@ Value Evaluator::evalFunctionCall(const oscad::PrimaryCall& node, EvalContext& c
             CallArgs args = resolveArgs(*this, node.arguments, ctx);
             return importAsValue(*this, args, node);
         }
-        // A builtin function name always wins over a same-named user
-        // function -- checked *before* the user-function lookup, not
-        // after, matching the reference's _eval_function_call precedence
-        // exactly (name in _BUILTIN_FN_NAMES gates which branch runs at
-        // all).
+        // A user-defined function SHADOWS a same-named builtin, so the
+        // user lookup runs FIRST. Verified against OpenSCAD 2026.02.01:
+        // `function norm(x) = 999; echo(norm([3,4]));` echoes 999 there,
+        // and 5 here until this was fixed.
+        //
+        // The comment this replaces asserted the opposite order matched
+        // "the reference's _eval_function_call precedence exactly" -- but
+        // _eval_function_call / _BUILTIN_FN_NAMES are the old PYTHON
+        // evaluator, not OpenSCAD, and that prototype had it backwards.
+        // The C++ port inherited the mistake. Modules were always right
+        // (a user `module sphere()` does override the builtin); only
+        // functions resolved the wrong way round.
+        //
+        // bytecode_compiler.cpp's Op::CallFn site resolution has the same
+        // ordering and is fixed with it -- the VM is the default engine,
+        // so fixing only this one would leave the bug in place.
+        const oscad::ASTNode* decl = ctx.scope->lookupFunction(leftId->name);
+        if (decl && decl->kind() == oscad::NodeKind::FunctionDeclaration) {
+            // Call-site stop, in the CALLER's context, before descending
+            // into the callee (whose own body-entry stop comes later, from
+            // evalUserFunctionCore). Builtins deliberately get none --
+            // only the user-function and function-literal branches stop.
+            checkDebug(node, ctx, /*forced=*/false, /*exprLevel=*/false, /*callSite=*/true);
+            return evalUserFunction(leftId->name, static_cast<const oscad::FunctionDeclaration&>(*decl), node.arguments,
+                                     ctx, &node);
+        }
         if (isBuiltinFunctionName(leftId->name)) {
             // is_undef(name) is a probe: asking whether a name is defined
             // must not itself warn that it isn't. The $-branch of
@@ -901,17 +922,6 @@ Value Evaluator::evalFunctionCall(const oscad::PrimaryCall& node, EvalContext& c
             CallArgs args = resolveArgs(*this, node.arguments, ctx);
             return evalBuiltinFunction(*this, leftId->name, args, node);
         }
-        const oscad::ASTNode* decl = ctx.scope->lookupFunction(leftId->name);
-        if (decl && decl->kind() == oscad::NodeKind::FunctionDeclaration) {
-            // Call-site stop, in the CALLER's context, before descending
-            // into the callee (whose own body-entry stop comes later, from
-            // evalUserFunctionCore). Builtins deliberately get none --
-            // mirrors _eval_function_call, where only the user-function and
-            // function-literal branches call _check_debug.
-            checkDebug(node, ctx, /*forced=*/false, /*exprLevel=*/false, /*callSite=*/true);
-            return evalUserFunction(leftId->name, static_cast<const oscad::FunctionDeclaration&>(*decl), node.arguments,
-                                     ctx, &node);
-        }
     }
 
     // Not a builtin or user function -- check whether the callee expression

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/tests/test_feature_detection.cpp

@@ -35,7 +35,7 @@ std::vector<std::string> echoesFrom(const std::string& src) {
 // in featureLevels() -- shows up as a 0.
 const char* kFeatures[] = {"separate-children", "minkowski-diff", "sphere-styles",   "export-name",
                             "simplify-op",       "expr-import",    "object-function", "roof-op",
-                            "render-expr",       "polyhedron-vnf"};
+                            "render-expr",       "polyhedron-vnf", "matrix-solve"};
 
 } // namespace
 

{openscad_cpp_evaluator-0.46.0 → openscad_cpp_evaluator-0.48.0}/tests/test_function_builtins.cpp

@@ -508,18 +508,99 @@ TEST(ObjectBuiltin, PositionalNonObjectNonListArgumentIsUndef) {
     EXPECT_TRUE(isUndef(evalSrc("object(5)", ev)));
 }
 
-// -- Precedence: a builtin function name always wins over a same-named --
-// user function, unlike modules (where a user module CAN shadow a builtin).
+// -- Precedence: a user function SHADOWS a same-named builtin ------------
+//
+// Same rule as modules, which always got this right. It used to be
+// backwards for functions: the builtin won, because the port copied the old
+// Python evaluator's _eval_function_call order rather than OpenSCAD's.
+//
+// Read off OpenSCAD 2026.02.01:
+//   function abs(x) = 999;  echo(abs(-3));            -> 999
+//   function is_undef(x) = "mine"; echo(is_undef(q)); -> "mine", and it
+//       WARNS about the unknown variable q, because a user function
+//       evaluates its arguments normally -- only the builtin probe is
+//       silent.
+//
+// Every case runs under both engines: the VM decides builtin-vs-user at
+// COMPILE time (bytecode_compiler.cpp), so it needs its own fix and its
+// own coverage.
 
-TEST(FunctionBuiltinPrecedence, BuiltinWinsOverSameNamedUserFunction) {
-    Evaluator ev;
-    auto ast = parseSrc("function abs(x) = 999;\nresult = abs(-3);");
-    auto scope = oscad::buildScopes(ast);
-    auto* assign = dynamic_cast<oscad::Assignment*>(ast[1].get());
-    ASSERT_NE(assign, nullptr);
-    EvalContext ctx = EvalContext::makeRoot(scope.get());
-    Value v = ev.evalExpr(*assign->expr, ctx);
-    EXPECT_DOUBLE_EQ(asNum(v), 3.0); // builtin abs(), not the user's abs()
+namespace {
+
+class ScopedVm {
+public:
+    explicit ScopedVm(bool enabled) { Evaluator::setBytecodeVmEnabledForTesting(enabled); }
+    ~ScopedVm() { Evaluator::setBytecodeVmEnabledForTesting(std::nullopt); }
+};
+
+std::vector<std::string> echoesOf(const std::string& src) {
+    std::vector<std::string> out;
+    oscadeval::test::evalSrc(src, [&](const std::string& m) { out.push_back(m); });
+    return out;
+}
+
+} // namespace
+
+TEST(FunctionBuiltinPrecedence, UserFunctionShadowsSameNamedBuiltin) {
+    for (bool vm : {false, true}) {
+        ScopedVm guard(vm);
+        const std::vector<std::string> e = echoesOf("function abs(x) = 999;\necho(abs(-3));");
+        ASSERT_EQ(e.size(), 1u) << "vm=" << vm;
+        EXPECT_NE(e[0].find("999"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+    }
+}
+
+TEST(FunctionBuiltinPrecedence, TheBuiltinStillWinsWhenNobodyRedefinesIt) {
+    for (bool vm : {false, true}) {
+        ScopedVm guard(vm);
+        const std::vector<std::string> e = echoesOf("echo(abs(-3));");
+        ASSERT_EQ(e.size(), 1u) << "vm=" << vm;
+        EXPECT_NE(e[0].find("3"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+        EXPECT_EQ(e[0].find("999"), std::string::npos) << "vm=" << vm;
+    }
+}
+
+TEST(FunctionBuiltinPrecedence, ShadowingHoldsInsideAUserFunctionBody) {
+    // The call is inside another function, so on the VM path it is reached
+    // through a COMPILED chunk rather than the interpreter -- this is the
+    // case a compiler-side fix is needed for.
+    for (bool vm : {false, true}) {
+        ScopedVm guard(vm);
+        const std::vector<std::string> e =
+            echoesOf("function abs(x) = 999;\nfunction outer() = abs(-3);\necho(outer());");
+        ASSERT_EQ(e.size(), 1u) << "vm=" << vm;
+        EXPECT_NE(e[0].find("999"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+    }
+}
+
+TEST(FunctionBuiltinPrecedence, AUserDefinedIsUndefShadowsTheProbe) {
+    // is_undef() is the one builtin with argument handling of its own (it
+    // must not warn about the name it is probing). A user's own is_undef
+    // takes over completely, arguments evaluated the ordinary way -- so the
+    // unknown-variable warning the probe suppresses DOES appear, exactly as
+    // upstream.
+    for (bool vm : {false, true}) {
+        ScopedVm guard(vm);
+        std::vector<std::string> msgs;
+        oscadeval::test::evalSrc("function is_undef(x) = \"mine\";\necho(is_undef(nothing));",
+                                  [&](const std::string& m) { msgs.push_back(m); });
+        bool sawMine = false, sawWarning = false;
+        for (const std::string& m : msgs) {
+            if (m.find("mine") != std::string::npos) sawMine = true;
+            if (m.find("nothing") != std::string::npos) sawWarning = true;
+        }
+        EXPECT_TRUE(sawMine) << "vm=" << vm;
+        EXPECT_TRUE(sawWarning) << "vm=" << vm << ": a user function evaluates its argument normally";
+    }
+}
+
+TEST(FunctionBuiltinPrecedence, TheIsUndefProbeIsStillSilentWhenNotRedefined) {
+    for (bool vm : {false, true}) {
+        ScopedVm guard(vm);
+        const std::vector<std::string> e = echoesOf("echo(is_undef(nothing));");
+        ASSERT_EQ(e.size(), 1u) << "vm=" << vm << ": probing must not warn";
+        EXPECT_NE(e[0].find("true"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+    }
 }
 
 // -- Builtin argument diagnostics (reference parity) ---------------------
@@ -644,3 +725,102 @@ TEST(StringListBuiltins, ChrIsVariadicAndRangeChecked) {
     EXPECT_EQ(asStr(evalSrc("chr(55296)", ev)), ""); // 0xD800, a surrogate
     EXPECT_EQ(asStr(evalSrc("chr(1114112)", ev)), ""); // 0x110000, one past the top
 }
+
+// -- matrix_solve(A, b) --------------------------------------------------
+//
+// One pivoted LU, three answers: x, det, singular. Oracle is BOSL2 plus
+// arithmetic -- OpenSCAD has no equivalent, so there is no reference
+// binary to compare against.
+//
+// Measured against BOSL2 through the CLI, same matrices, identical
+// determinants: n=10  3.17s -> 0.33s, n=11  31.49s -> 0.33s. BOSL2's
+// determinant() is a cofactor expansion, growing x10 per step; this is
+// O(n^3).
+
+TEST(MatrixSolve, SolvesASquareSystem) {
+    Evaluator ev;
+    // asList() returns a reference INTO v, so v has to outlive it -- taking
+    // asList(evalSrc(...)) directly dangles the moment the temporary dies.
+    const Value v = evalSrc("matrix_solve([[2,1],[1,3]], [5,10]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 2u);
+    EXPECT_NEAR(asNum(x[0]), 1.0, 1e-12);
+    EXPECT_NEAR(asNum(x[1]), 3.0, 1e-12);
+}
+
+TEST(MatrixSolve, DeterminantComesFreeFromTheSameFactorisation) {
+    Evaluator ev;
+    EXPECT_NEAR(asNum(evalSrc("matrix_solve([[2,1],[1,3]]).det", ev)), 5.0, 1e-12);
+    EXPECT_NEAR(asNum(evalSrc("matrix_solve([[1,0,0],[0,1,0],[0,0,1]]).det", ev)), 1.0, 1e-12);
+    // Sign follows the row swaps, not just the magnitude.
+    EXPECT_NEAR(asNum(evalSrc("matrix_solve([[0,1],[1,0]]).det", ev)), -1.0, 1e-12);
+}
+
+TEST(MatrixSolve, WithNoRightHandSideThereIsNoSolution) {
+    Evaluator ev;
+    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[2,1],[1,3]]).x", ev)));
+}
+
+TEST(MatrixSolve, ASingularMatrixAnswersRatherThanWarning) {
+    // "Is this matrix singular?" is a fair question to ask, so it is
+    // reported, not warned about: det 0, singular true, no solution.
+    Evaluator ev;
+    EXPECT_TRUE(asBool(evalSrc("matrix_solve([[1,2],[2,4]], [1,2]).singular", ev)));
+    EXPECT_NEAR(asNum(evalSrc("matrix_solve([[1,2],[2,4]], [1,2]).det", ev)), 0.0, 1e-12);
+    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[2,4]], [1,2]).x", ev)));
+}
+
+TEST(MatrixSolve, SingularityIsRelativeToTheMatrixNotAbsolute) {
+    // 2*I scaled by 1e-10 is perfectly conditioned, and BOSL2's
+    // linear_solve calls it singular -- its test is a fixed absolute 1e-9
+    // on R's diagonal with no scaling by the size of the matrix. Verified
+    // through the CLI: BOSL2 says SINGULAR at 1e-10 and 1e-12 where this
+    // solves correctly.
+    Evaluator ev;
+    EXPECT_FALSE(asBool(evalSrc("matrix_solve([[2e-10,0],[0,2e-10]], [1e-10,1e-10]).singular", ev)));
+    const Value v = evalSrc("matrix_solve([[2e-10,0],[0,2e-10]], [1e-10,1e-10]).x", ev);
+    const std::vector<Value>& x = asList(v);
+    ASSERT_EQ(x.size(), 2u);
+    EXPECT_NEAR(asNum(x[0]), 0.5, 1e-9);
+}
+
+TEST(MatrixSolve, AMatrixRightHandSideSolvesEveryColumn) {
+    Evaluator ev;
+    // Solving against the identity is the inverse; [[2,1],[1,3]] has
+    // det 5, so the inverse is [[0.6,-0.2],[-0.2,0.4]].
+    const Value v = evalSrc("matrix_solve([[2,1],[1,3]], [[1,0],[0,1]]).x", ev);
+    const std::vector<Value>& rows = asList(v);
+    ASSERT_EQ(rows.size(), 2u);
+    const std::vector<Value>& r0 = asList(rows[0]);
+    ASSERT_EQ(r0.size(), 2u);
+    EXPECT_NEAR(asNum(r0[0]), 0.6, 1e-12);
+    EXPECT_NEAR(asNum(r0[1]), -0.2, 1e-12);
+}
+
+TEST(MatrixSolve, RejectsWhatItCannotFactor) {
+    Evaluator ev;
+    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2,3],[4,5,6]], [1,2])", ev)));   // not square
+    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[3,\"x\"]], [1,2])", ev)));   // not numeric
+    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[3,4]], [1,2,3])", ev)));     // wrong rhs length
+    EXPECT_TRUE(isUndef(evalSrc("matrix_solve([[1,2],[3,4,5]], [1,2])", ev)));     // ragged
+}
+
+TEST(MatrixSolve, NonSquareWarnsWithItsShape) {
+    const std::vector<std::string> w = builtinWarnings("matrix_solve([[1,2,3],[4,5,6]], [1,2])");
+    ASSERT_EQ(w.size(), 1u);
+    EXPECT_NE(w[0].find("matrix_solve() requires a square matrix, found 2 x 3"), std::string::npos)
+        << "got " << w[0];
+}
+
+TEST(MatrixSolve, WorksUnderBothEngines) {
+    for (bool vm : {false, true}) {
+        ScopedVm guard(vm);
+        const std::vector<std::string> e =
+            echoesOf("r = matrix_solve([[2,1],[1,3]], [5,10]);\necho(r.x, r.det, r.singular);");
+        ASSERT_EQ(e.size(), 1u) << "vm=" << vm;
+        EXPECT_NE(e[0].find("[1, 3]"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+        EXPECT_NE(e[0].find("5"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+        EXPECT_NE(e[0].find("false"), std::string::npos) << "vm=" << vm << ", got " << e[0];
+    }
+}
+