Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/compiler.py

@@ -0,0 +1,1721 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .board import BoardProfile, UNO
+from .errors import BarmajaError, CompileError, InternalCompilerError
+from .frontend import FrontendModule, is_noop_stmt, validate_frontend
+from .flow import FlowAnalyzedModule, StorageClass, analyze_flow
+from .source import ParsedSource, load_source_file, parse_source_text
+from .symbols import ResolvedModule, SymbolKind, resolve_symbols
+from .typesys import TypedModule, TypeKind, analyze_types
+from .numeric import NumericAnalysis, analyze_numeric_ranges
+from .ir import IRModule
+from .lowering import lower_to_ir
+from .target import TargetPlan, TargetDiagnostic, analyze_target
+from .backend import GeneratedSketch, generate_uno_cpp
+from .api_registry import CORE_FUNCTIONS, HARDWARE_CLASSES as API_HARDWARE_CLASSES, HOST_COMMANDS, SINGLETONS
+
+CORE_CALLS = frozenset(CORE_FUNCTIONS)
+BUILTIN_CALLS = {"round", "min", "max", "abs", "int", "float", "bool", "len", "sum", "enumerate"}
+HARDWARE_CLASSES = frozenset(API_HARDWARE_CLASSES)
+OBJECT_METHODS = {name: frozenset(spec.methods) for name, spec in API_HARDWARE_CLASSES.items()}
+SINGLETON_METHODS = {name: frozenset(spec.methods) for name, spec in SINGLETONS.items()}
+CONSTANTS = {
+    "HIGH", "LOW", "INPUT", "OUTPUT", "INPUT_PULLUP",
+    "A0", "A1", "A2", "A3", "A4", "A5",
+}
+
+
+@dataclass
+class Program:
+    globals: list[ast.Assign] = field(default_factory=list)
+    objects: list[ast.Assign] = field(default_factory=list)
+    functions: list[ast.FunctionDef] = field(default_factory=list)
+    setup: list[ast.stmt] = field(default_factory=list)
+    loop: list[ast.stmt] = field(default_factory=list)
+    imports: set[str] = field(default_factory=set)
+    uses_print: bool = False
+    used_singletons: set[str] = field(default_factory=set)
+
+
+@dataclass
+class CompileResult:
+    source_path: Path | None
+    cpp: str
+    program: Program
+    board: BoardProfile
+    parsed_source: ParsedSource | None = None
+    resolved_module: ResolvedModule | None = None
+    flow_analyzed_module: FlowAnalyzedModule | None = None
+    typed_module: TypedModule | None = None
+    numeric_analysis: NumericAnalysis | None = None
+    ir_module: IRModule | None = None
+    target_plan: TargetPlan | None = None
+    generated_sketch: GeneratedSketch | None = None
+    warnings: tuple[TargetDiagnostic, ...] = ()
+
+
+@dataclass
+class FunctionInfo:
+    return_type: str
+    param_types: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class _OutputPart:
+    literal: str | None = None
+    expression: str | None = None
+    type_kind: TypeKind | None = None
+    precision: int | None = None
+
+
+def _is_host_command_stmt(stmt: ast.stmt) -> bool:
+    return (
+        isinstance(stmt, ast.Expr)
+        and isinstance(stmt.value, ast.Call)
+        and isinstance(stmt.value.func, ast.Name)
+        and stmt.value.func.id in HOST_COMMANDS
+    )
+
+
+def _strip_host_commands(parsed: ParsedSource) -> ParsedSource:
+    """Remove top-level host workflow lines such as `upload()` and `LiveRun()`.
+
+    They are PC-side workflow commands (PictoBlox/IDE "Run" button) and never
+    part of the Arduino program. Any other use is a clear student error.
+    """
+    import dataclasses
+    body = [stmt for stmt in parsed.tree.body if not _is_host_command_stmt(stmt)]
+    for node in ast.walk(ast.Module(body=body, type_ignores=[])):
+        if isinstance(node, ast.Name) and node.id in HOST_COMMANDS:
+            raise CompileError(
+                f"{node.id}() must be written on its own line at the top level of the program (for example right after the import).",
+                getattr(node, "lineno", None),
+                (getattr(node, "col_offset", 0) or 0) + 1,
+            )
+    if len(body) == len(parsed.tree.body):
+        return parsed
+    tree = ast.Module(body=body, type_ignores=list(getattr(parsed.tree, "type_ignores", [])))
+    return dataclasses.replace(parsed, tree=tree)
+
+
+class Transpiler:
+    def __init__(self, board: BoardProfile = UNO):
+        self.board = board
+        self._global_values: dict[str, object] = {}
+        self._functions: dict[str, FunctionInfo] = {}
+        self._objects: dict[str, str] = {}
+        self._resolved: ResolvedModule | None = None
+        self._flow: FlowAnalyzedModule | None = None
+        self._typed: TypedModule | None = None
+        self._numeric: NumericAnalysis | None = None
+        self._target_plan: TargetPlan | None = None
+        self._temp_counter = 0
+
+    def _reset_state(self) -> None:
+        # One Transpiler instance may compile multiple independent student files.
+        self._global_values = {}
+        self._functions = {}
+        self._objects = {}
+        self._resolved = None
+        self._flow = None
+        self._typed = None
+        self._numeric = None
+        self._target_plan = None
+        self._temp_counter = 0
+
+    def _compile_parsed(self, parsed: ParsedSource, source_path: Path | None = None) -> CompileResult:
+        self._reset_state()
+        try:
+            parsed = _strip_host_commands(parsed)
+            frontend = validate_frontend(parsed.tree)
+            resolved = resolve_symbols(frontend)
+            self._resolved = resolved
+            flow = analyze_flow(resolved)
+            self._flow = flow
+            # Program is retained only as a compatibility/introspection view.  It is
+            # classified before type/IR phases so no production phase after typed
+            # lowering depends on raw Python AST semantics.
+            program = self._classify(frontend)
+            typed = analyze_types(flow)
+            self._typed = typed
+            numeric = analyze_numeric_ranges(typed)
+            self._numeric = numeric
+            ir_module = lower_to_ir(typed, numeric, parsed.filename)
+            target_plan = analyze_target(ir_module, numeric, self.board)
+            self._target_plan = target_plan
+            generated = generate_uno_cpp(ir_module, target_plan)
+            return CompileResult(
+                source_path=source_path,
+                cpp=generated.cpp,
+                program=program,
+                board=self.board,
+                parsed_source=parsed,
+                resolved_module=resolved,
+                flow_analyzed_module=flow,
+                typed_module=typed,
+                numeric_analysis=numeric,
+                ir_module=ir_module,
+                target_plan=target_plan,
+                generated_sketch=generated,
+                warnings=target_plan.warnings,
+            )
+        except RecursionError:
+            raise CompileError(
+                "This expression or statement is nested too deeply for Barmaja PyArduino. Split it into smaller steps.",
+                None,
+            ) from None
+        except BarmajaError as exc:
+            # Attach the source identity without changing existing error wording.
+            if getattr(exc, "source", None) is None:
+                exc.source = parsed.filename
+            raise
+        except Exception as exc:
+            # Student code must never surface raw IndexError/KeyError/etc.  The
+            # detailed root cause is retained for trainer/developer diagnostics.
+            raise InternalCompilerError(
+                "An internal compiler error occurred while processing this program.",
+                source=parsed.filename,
+                details=f"{type(exc).__name__}: {exc}",
+            ) from None
+
+    def compile_text(self, source: str, source_path: Path | None = None) -> CompileResult:
+        parsed = parse_source_text(source, source_path)
+        return self._compile_parsed(parsed, source_path)
+
+    def compile_file(self, path: str | Path) -> CompileResult:
+        p = Path(path)
+        parsed = load_source_file(p)
+        return self._compile_parsed(parsed, p)
+
+    # ---------- classification / validation ----------
+    def _classify(self, frontend: FrontendModule) -> Program:
+        tree = frontend.tree
+        p = Program()
+        main_loop_seen = False
+        for node in tree.body:
+            if isinstance(node, ast.ImportFrom):
+                if node.module != "Barmaja_PyArduino":
+                    raise CompileError(
+                        "Arduino projects may only import supported Barmaja PyArduino modules.",
+                        node.lineno, node.col_offset + 1,
+                    )
+                p.imports.update(alias.name for alias in node.names)
+                continue
+            if isinstance(node, ast.Import):
+                raise CompileError("Use 'from Barmaja_PyArduino import ...' in Arduino projects.", node.lineno)
+            if is_noop_stmt(node, docstring_allowed=True) and not main_loop_seen:
+                continue
+            if isinstance(node, ast.FunctionDef) and not main_loop_seen:
+                p.functions.append(node)
+                continue
+            if isinstance(node, ast.Assign) and not main_loop_seen and self._is_hardware_object_assignment(node):
+                p.objects.append(node)
+                continue
+            if isinstance(node, ast.Assign) and not main_loop_seen and self._is_compile_time_assignment(node):
+                # Step 6: a literal assignment is file-scope only when flow
+                # analysis proves constant/persistent module storage. Mutable
+                # setup-only values remain setup locals.
+                storages = []
+                if self._flow is not None:
+                    targets = [node.targets[0]]
+                    if isinstance(node.targets[0], (ast.Tuple, ast.List)):
+                        targets = list(node.targets[0].elts)
+                    for target in targets:
+                        if isinstance(target, ast.Name):
+                            sym = self._resolved.symbol_for_name(target) if self._resolved is not None else None
+                            if sym is not None:
+                                storages.append(self._flow.storage_for(sym))
+                if storages and all(x in {StorageClass.MODULE_CONSTANT, StorageClass.PERSISTENT_MODULE} for x in storages):
+                    p.globals.append(node)
+                else:
+                    p.setup.append(node)
+                continue
+            if isinstance(node, ast.While) and self._is_true(node.test):
+                if main_loop_seen:
+                    raise CompileError("Only one top-level 'while True:' main loop is allowed.", node.lineno)
+                if node.orelse:
+                    raise CompileError("The main 'while True:' loop cannot have an else block.", node.lineno)
+                main_loop_seen = True
+                p.loop.extend(node.body)
+                continue
+            if main_loop_seen:
+                raise CompileError("Nothing may follow the main top-level 'while True:' loop.", getattr(node, "lineno", None))
+            p.setup.append(node)
+        return p
+
+    @staticmethod
+    def _is_true(node: ast.AST) -> bool:
+        return isinstance(node, ast.Constant) and node.value is True
+
+
+    @staticmethod
+    def _is_hardware_object_assignment(node: ast.Assign) -> bool:
+        return (
+            len(node.targets) == 1
+            and isinstance(node.targets[0], ast.Name)
+            and isinstance(node.value, ast.Call)
+            and isinstance(node.value.func, ast.Name)
+            and node.value.func.id in HARDWARE_CLASSES
+        )
+
+    @staticmethod
+    def _is_compile_time_assignment(node: ast.Assign) -> bool:
+        if len(node.targets) != 1:
+            return False
+        target = node.targets[0]
+        if isinstance(target, ast.Name):
+            if isinstance(node.value, (ast.Constant, ast.UnaryOp)):
+                return True
+            if isinstance(node.value, ast.List) and node.value.elts:
+                return all(isinstance(v, (ast.Constant, ast.UnaryOp)) for v in node.value.elts)
+            return False
+        if isinstance(target, (ast.Tuple, ast.List)) and isinstance(node.value, (ast.Tuple, ast.List)):
+            return len(target.elts) == len(node.value.elts) and all(isinstance(t, ast.Name) for t in target.elts) and all(
+                isinstance(v, (ast.Constant, ast.UnaryOp)) for v in node.value.elts
+            )
+        return False
+
+    # LEGACY REFERENCE BACKEND (Steps 1-14)
+    # ---------------------------------------
+    # Step 15 retired the methods below from the production compile pipeline.
+    # They are temporarily retained as a regression/reference implementation
+    # while Step 16+ stabilizes packaging/toolchain work. Production Phase H
+    # uses backend.uno_cpp.generate_uno_cpp(IRModule, TargetPlan) exclusively.
+    def _analyze(self, p: Program) -> None:
+        for node in p.globals:
+            self._infer_global(node)
+        for node in p.objects:
+            name = node.targets[0].id
+            class_name = node.value.func.id
+            self._objects[name] = class_name
+            for arg in node.value.args:
+                self._validate_expr(arg, p)
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during compiler validation.")
+        for fn in p.functions:
+            signature = self._typed.signature_for(fn.name)
+            self._functions[fn.name] = FunctionInfo(
+                signature.return_type.cpp_type,
+                tuple(t.cpp_type for t in signature.parameter_types),
+            )
+        for fn in p.functions:
+            self._validate_function(fn, p)
+        for stmt in [*p.setup, *p.loop]:
+            self._validate_stmt(stmt, p)
+
+    def _infer_global(self, node: ast.Assign) -> None:
+        target = node.targets[0]
+        pairs = [(target, node.value)] if isinstance(target, ast.Name) else list(zip(target.elts, node.value.elts))
+        for name_node, value_node in pairs:
+            self._global_values[name_node.id] = self._literal_python_value(value_node)
+
+    def _validate_function(self, fn: ast.FunctionDef, p: Program) -> None:
+        if fn.decorator_list:
+            raise CompileError("Decorators are not supported in Barmaja PyArduino V1.", fn.lineno)
+        if fn.args.vararg or fn.args.kwarg or fn.args.kwonlyargs:
+            raise CompileError("Use simple positional function parameters in Barmaja PyArduino V1.", fn.lineno)
+        for stmt in fn.body:
+            self._validate_stmt(stmt, p, in_function=True)
+
+    def _validate_stmt(self, node: ast.stmt, p: Program, in_function: bool = False) -> None:
+        if is_noop_stmt(node, docstring_allowed=True):
+            return
+        if isinstance(node, ast.Expr):
+            if not isinstance(node.value, ast.Call):
+                raise CompileError("Only supported function calls may be standalone statements here.", node.lineno)
+            self._validate_call(node.value, p)
+            return
+        if isinstance(node, ast.Assign):
+            if len(node.targets) != 1:
+                raise CompileError("Chained assignment is not supported in V1.", node.lineno)
+            target = node.targets[0]
+            if not isinstance(target, (ast.Name, ast.Subscript)):
+                raise CompileError("Use a variable name or fixed-list item assignment.", node.lineno)
+            if isinstance(target, ast.Subscript):
+                self._validate_expr(target, p)
+            self._validate_expr(node.value, p)
+            return
+        if isinstance(node, ast.AugAssign):
+            if not isinstance(node.target, ast.Name) or not isinstance(node.op, (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.Mod)):
+                raise CompileError("This augmented assignment is not supported yet.", node.lineno)
+            self._validate_expr(node.value, p)
+            return
+        if isinstance(node, ast.If):
+            self._validate_expr(node.test, p)
+            for s in node.body + node.orelse:
+                self._validate_stmt(s, p, in_function)
+            return
+        if isinstance(node, ast.While):
+            self._validate_expr(node.test, p)
+            for s in node.body:
+                self._validate_stmt(s, p, in_function)
+            return
+        if isinstance(node, ast.For):
+            if isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "range":
+                if not isinstance(node.target, ast.Name):
+                    raise CompileError("range() loop target must be a simple name.", node.lineno)
+                self._parse_range(node.iter, node, p)
+            elif isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "enumerate":
+                self._validate_call(node.iter, p)
+            else:
+                self._validate_expr(node.iter, p)
+            for s in node.body:
+                self._validate_stmt(s, p, in_function)
+            if node.orelse:
+                raise CompileError("for/else is not supported in Barmaja PyArduino V1.", node.lineno)
+            return
+        if isinstance(node, ast.Return) and in_function:
+            if node.value is not None:
+                self._validate_expr(node.value, p)
+            return
+        if isinstance(node, ast.Global) and in_function:
+            # Phase C has already validated and resolved restricted global names.
+            return
+        if isinstance(node, (ast.Break, ast.Continue)):
+            # Phase D has already resolved/validated the loop target.
+            return
+        raise CompileError(f"'{type(node).__name__}' is not supported yet.", getattr(node, "lineno", None))
+
+    def _validate_expr(self, node: ast.AST, p: Program) -> None:
+        if isinstance(node, (ast.Constant, ast.Name)):
+            return
+        if isinstance(node, ast.JoinedStr):
+            for v in node.values:
+                if isinstance(v, ast.FormattedValue):
+                    self._validate_expr(v.value, p)
+            return
+        if isinstance(node, ast.Call):
+            self._validate_call(node, p)
+            return
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.Not)):
+            self._validate_expr(node.operand, p); return
+        if isinstance(node, ast.BinOp) and isinstance(node.op, (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.Mod)):
+            self._validate_expr(node.left, p); self._validate_expr(node.right, p); return
+        if isinstance(node, ast.Compare):
+            self._validate_expr(node.left, p)
+            for c in node.comparators: self._validate_expr(c, p)
+            return
+        if isinstance(node, ast.BoolOp) and isinstance(node.op, (ast.And, ast.Or)):
+            for v in node.values: self._validate_expr(v, p)
+            return
+        if isinstance(node, ast.IfExp):
+            self._validate_expr(node.test, p); self._validate_expr(node.body, p); self._validate_expr(node.orelse, p); return
+        if isinstance(node, ast.List):
+            for item in node.elts: self._validate_expr(item, p)
+            return
+        if isinstance(node, ast.Subscript):
+            self._validate_expr(node.value, p); self._validate_expr(node.slice, p); return
+        raise CompileError(f"Expression '{type(node).__name__}' is not supported yet.", getattr(node, "lineno", None))
+
+    def _validate_call(self, node: ast.Call, p: Program) -> None:
+        if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            owner = node.func.value.id
+            method = node.func.attr
+            if owner in self._objects:
+                cls = self._objects[owner]
+                if method not in OBJECT_METHODS[cls]:
+                    raise CompileError(f"{cls}.{method}() is not supported in Barmaja PyArduino V1.", node.lineno)
+            elif owner in SINGLETON_METHODS:
+                if method not in SINGLETON_METHODS[owner]:
+                    raise CompileError(f"{owner}.{method}() is not supported in Barmaja PyArduino V1.", node.lineno)
+                p.used_singletons.add(owner)
+            else:
+                raise CompileError(f"Unknown Arduino object '{owner}'.", node.lineno)
+            for arg in node.args:
+                self._validate_expr(arg, p)
+            if node.keywords:
+                raise CompileError("Keyword arguments are not supported for Arduino library methods.", node.lineno)
+            return
+        if not isinstance(node.func, ast.Name):
+            raise CompileError("Unsupported call form.", node.lineno)
+        name = node.func.id
+        if name == "print":
+            p.uses_print = True
+            for arg in node.args: self._validate_expr(arg, p)
+            if node.keywords:
+                raise CompileError("Custom print() sep/end are not supported in V1.", node.lineno)
+            return
+        if name not in CORE_CALLS and name not in BUILTIN_CALLS and name not in self._functions:
+            raise CompileError(f"'{name}' is not a supported Barmaja PyArduino call yet.", node.lineno)
+        for arg in node.args: self._validate_expr(arg, p)
+        if node.keywords:
+            raise CompileError("Keyword arguments are not supported for this call.", node.lineno)
+
+    # ---------- resolved backend names ----------
+    def _resolved_name(self, node: ast.Name) -> str:
+        if self._resolved is None:
+            raise InternalCompilerError("Symbol resolution is unavailable during code generation.")
+        try:
+            return self._resolved.symbol_for_name(node).cpp_name
+        except KeyError:
+            raise InternalCompilerError(
+                "A source name reached code generation without a resolved binding.",
+                line=getattr(node, "lineno", None),
+                details=f"unresolved name: {node.id}",
+            ) from None
+
+    def _resolved_function_name(self, fn: ast.FunctionDef) -> str:
+        if self._resolved is None:
+            raise InternalCompilerError("Symbol resolution is unavailable during code generation.")
+        try:
+            return self._resolved.symbol_for_function(fn).cpp_name
+        except KeyError:
+            raise InternalCompilerError(
+                "A function reached code generation without a resolved binding.",
+                line=getattr(fn, "lineno", None),
+                details=f"unresolved function: {fn.name}",
+            ) from None
+
+    def _resolved_parameter_name(self, arg: ast.arg) -> str:
+        if self._resolved is None:
+            raise InternalCompilerError("Symbol resolution is unavailable during code generation.")
+        try:
+            return self._resolved.symbol_for_parameter(arg).cpp_name
+        except KeyError:
+            raise InternalCompilerError(
+                "A function parameter reached code generation without a resolved binding.",
+                line=getattr(arg, "lineno", None),
+                details=f"unresolved parameter: {arg.arg}",
+            ) from None
+
+    # ---------- C++ generation ----------
+    def _generate(self, p: Program) -> str:
+        if self._resolved is None or self._flow is None:
+            raise InternalCompilerError("Flow/symbol analysis is unavailable during code generation.")
+
+        if self._target_plan is None:
+            raise InternalCompilerError("Target analysis is unavailable during code generation.")
+        includes = [f"#include <{header}>" for header in self._target_plan.includes]
+        lines = [
+            "// Generated by Barmaja PyArduino 0.6.0",
+            "// Edit the Python source, not this generated file.",
+            *includes, "",
+        ]
+        helpers = self._numeric_helper_lines()
+        if helpers:
+            lines.extend(helpers)
+            lines.append("")
+        output_helpers = self._output_helper_lines()
+        if output_helpers:
+            lines.extend(output_helpers)
+            lines.append("")
+
+        initialized_global_ids = set()
+        for node in p.globals:
+            target = node.targets[0]
+            pairs = [(target, node.value)] if isinstance(target, ast.Name) else list(zip(target.elts, node.value.elts))
+            for t, v in pairs:
+                symbol = self._resolved.symbol_for_name(t)
+                initialized_global_ids.add(symbol.symbol_id)
+                typ_obj = self._typed.type_for_symbol(symbol) if self._typed is not None else None
+                if typ_obj is not None and typ_obj.kind == TypeKind.FIXED_LIST:
+                    if not isinstance(v, ast.List):
+                        raise InternalCompilerError("Fixed list reached global generation without a list initializer.")
+                    const_prefix = "const " if self._flow.storage_for(symbol) == StorageClass.MODULE_CONSTANT else ""
+                    elem = typ_obj.element_type.cpp_type if typ_obj.element_type is not None else "int32_t"
+                    items = ", ".join(self._expr(x) for x in v.elts)
+                    lines.append(f"{const_prefix}{elem} {symbol.cpp_name}[{typ_obj.length}] = {{{items}}};")
+                else:
+                    typ = self._cpp_type_for_symbol(symbol)
+                    if self._flow.storage_for(symbol) == StorageClass.MODULE_CONSTANT:
+                        decl_type = "const char* const" if typ == "const char*" else f"const {typ}"
+                    else:
+                        decl_type = typ
+                    lines.append(f"{decl_type} {symbol.cpp_name} = {self._expr(v)};")
+
+        # Persistent state whose initialization must execute in setup/loop is
+        # allocated exactly once at file scope, without moving the assignment.
+        persistent = [
+            fact.symbol for fact in self._flow.symbol_facts.values()
+            if fact.storage == StorageClass.PERSISTENT_MODULE
+            and fact.symbol.symbol_id not in initialized_global_ids
+        ]
+        for symbol in sorted(persistent, key=lambda x: (x.declaration_line or 10**9, x.symbol_id.value)):
+            lines.append(self._declaration_line(symbol))
+        if p.globals or persistent:
+            lines.append("")
+
+        for node in p.objects:
+            target = node.targets[0]
+            name = self._resolved_name(target)
+            cls = node.value.func.id
+            args = ", ".join(self._expr(a) for a in node.value.args)
+            lines.append(f"{cls} {name}({args});" if args else f"{cls} {name};")
+        if p.objects:
+            lines.append("")
+
+        # Function prototypes make source-order irrelevant after Phase C/D.
+        for fn in p.functions:
+            info = self._functions[fn.name]
+            params = ", ".join(f"{typ} {self._resolved_parameter_name(a)}" for typ, a in zip(info.param_types, fn.args.args))
+            lines.append(f"{info.return_type} {self._resolved_function_name(fn)}({params});")
+        if p.functions:
+            lines.append("")
+
+        for fn in p.functions:
+            lines.extend(self._function(fn)); lines.append("")
+
+        lines.append("void setup() {")
+        setup_symbols = self._symbols_with_storage(StorageClass.SETUP_LOCAL)
+        setup_scope = self._module_predeclared_cpp_names(StorageClass.PERSISTENT_MODULE, StorageClass.MODULE_CONSTANT, StorageClass.HARDWARE_PERSISTENT)
+        for symbol in setup_symbols:
+            lines.append("    " + self._declaration_line(symbol))
+            setup_scope.add(symbol.cpp_name)
+        for hook in self._target_plan.setup_hooks:
+            lines.append("    " + hook)
+        for stmt in p.setup:
+            lines.extend(self._stmt(stmt, 1, setup_scope, p, loop_stack=()))
+        lines.append("}")
+        lines.append("")
+
+        lines.append("void loop() {")
+        loop_symbols = self._symbols_with_storage(StorageClass.LOOP_TEMPORARY)
+        loop_scope = self._module_predeclared_cpp_names(StorageClass.PERSISTENT_MODULE, StorageClass.MODULE_CONSTANT, StorageClass.HARDWARE_PERSISTENT)
+        for symbol in loop_symbols:
+            lines.append("    " + self._declaration_line(symbol))
+            loop_scope.add(symbol.cpp_name)
+        for stmt in p.loop:
+            lines.extend(self._stmt(stmt, 1, loop_scope, p, loop_stack=("main",)))
+        lines.append("}")
+        lines.append("")
+        return "\n".join(lines)
+
+    def _function(self, fn: ast.FunctionDef) -> list[str]:
+        if self._resolved is None or self._flow is None:
+            raise InternalCompilerError("Flow/symbol analysis is unavailable during function generation.")
+        info = self._functions[fn.name]
+        params = ", ".join(f"{typ} {self._resolved_parameter_name(a)}" for typ, a in zip(info.param_types, fn.args.args))
+        out = [f"{info.return_type} {self._resolved_function_name(fn)}({params}) {{"]
+        scope = {self._resolved_parameter_name(a) for a in fn.args.args}
+        fn_scope = self._resolved.function_scopes.get(fn.name)
+        if fn_scope is not None:
+            for global_name in fn_scope.global_names:
+                module_symbol = self._resolved.module_scope.symbols.get(global_name)
+                if module_symbol is not None:
+                    scope.add(module_symbol.cpp_name)
+            locals_ = [
+                sym for sym in fn_scope.symbols.values()
+                if self._flow.storage_for(sym) == StorageClass.FUNCTION_LOCAL
+            ]
+            for symbol in sorted(locals_, key=lambda x: (x.declaration_line or 10**9, x.symbol_id.value)):
+                out.append("    " + self._declaration_line(symbol))
+                scope.add(symbol.cpp_name)
+        dummy = Program()  # statement generator only; analysis already completed
+        for stmt in fn.body:
+            out.extend(self._stmt(stmt, 1, scope, dummy, loop_stack=()))
+        out.append("}")
+        return out
+
+    def _stmt(
+        self,
+        node: ast.stmt,
+        indent: int,
+        scope: set[str],
+        p: Program,
+        *,
+        loop_stack: tuple[str, ...],
+    ) -> list[str]:
+        pad = "    " * indent
+        if is_noop_stmt(node, docstring_allowed=True):
+            return []
+        if isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):
+            if isinstance(node.value.func, ast.Name) and node.value.func.id == "print":
+                return self._serial_print(node.value, indent)
+            if isinstance(node.value.func, ast.Attribute) and node.value.func.attr in {"print", "println"}:
+                owner_node = node.value.func.value
+                if isinstance(owner_node, ast.Name):
+                    owner_source = owner_node.id
+                    is_supported_sink = owner_source == "Serial" or self._objects.get(owner_source) == "LiquidCrystal_I2C"
+                    if is_supported_sink:
+                        special = self._explicit_output_stmt(node.value, indent)
+                        if special is not None:
+                            return special
+            return [pad + self._expr(node.value) + ";"]
+        if isinstance(node, ast.Assign):
+            target = node.targets[0]
+            if isinstance(target, ast.Subscript):
+                return [f"{pad}{self._subscript_lvalue(target)} = {self._expr(node.value)};"]
+            if not isinstance(target, ast.Name):
+                raise InternalCompilerError("Unsupported assignment target reached backend.", line=getattr(node, "lineno", None))
+            name = self._resolved_name(target)
+            symbol = self._resolved.symbol_for_name(target) if self._resolved is not None else None
+            typ_obj = self._typed.type_for_symbol(symbol) if (self._typed is not None and symbol is not None) else None
+            if typ_obj is not None and typ_obj.kind == TypeKind.FIXED_LIST:
+                if not isinstance(node.value, ast.List):
+                    raise CompileError("Whole fixed-list reassignment is not supported in V1; update individual items instead.", node.lineno)
+                items = [self._expr(x) for x in node.value.elts]
+                if name in scope:
+                    return [f"{pad}{name}[{i}] = {value};" for i, value in enumerate(items)]
+                scope.add(name)
+                elem = typ_obj.element_type.cpp_type if typ_obj.element_type is not None else "int32_t"
+                return [f"{pad}{elem} {name}[{typ_obj.length}] = {{{', '.join(items)}}};"]
+            expr = self._expr(node.value)
+            if name in scope:
+                return [f"{pad}{name} = {expr};"]
+            scope.add(name)
+            typ = self._infer_expr_type(node.value)
+            return [f"{pad}{typ} {name} = {expr};"]
+        if isinstance(node, ast.AugAssign):
+            target_name = self._resolved_name(node.target)
+            target_type = self._typed.type_for_expr(node.target) if self._typed is not None else None
+            rhs = self._expr(node.value)
+            if isinstance(node.op, ast.Div):
+                return [f"{pad}{target_name} = _bj_true_div_f32((float)({target_name}), (float)({rhs}));"]
+            if isinstance(node.op, ast.Mod):
+                if target_type is not None and target_type.kind == TypeKind.FLOAT:
+                    return [f"{pad}{target_name} = _bj_mod_f32((float)({target_name}), (float)({rhs}));"]
+                return [f"{pad}{target_name} = _bj_mod_i32({target_name}, {rhs});"]
+            if target_type is not None and target_type.kind == TypeKind.INT and isinstance(node.op, (ast.Add, ast.Sub, ast.Mult)):
+                helper = {ast.Add: "_bj_i32_add", ast.Sub: "_bj_i32_sub", ast.Mult: "_bj_i32_mul"}[type(node.op)]
+                return [f"{pad}{target_name} = {helper}({target_name}, {rhs});"]
+            ops = {ast.Add: "+=", ast.Sub: "-=", ast.Mult: "*="}
+            return [f"{pad}{target_name} {ops[type(node.op)]} {rhs};"]
+        if isinstance(node, ast.Return):
+            return [pad + ("return;" if node.value is None else f"return {self._expr(node.value)};")]
+        if isinstance(node, ast.Global):
+            return []
+        if isinstance(node, ast.Break):
+            if not loop_stack:
+                raise InternalCompilerError("break reached the backend without a loop target.", line=getattr(node, "lineno", None))
+            if loop_stack[-1] == "main":
+                raise InternalCompilerError("A main-loop break passed flow validation.", line=getattr(node, "lineno", None))
+            return [pad + "break;"]
+        if isinstance(node, ast.Continue):
+            if not loop_stack:
+                raise InternalCompilerError("continue reached the backend without a loop target.", line=getattr(node, "lineno", None))
+            # The special Python main while is represented by repeated calls to
+            # Arduino loop(); finishing this call is Python's next iteration.
+            return [pad + ("return;" if loop_stack[-1] == "main" else "continue;")]
+        if isinstance(node, ast.If):
+            out = [f"{pad}if ({self._expr(node.test)}) {{"]
+            child = set(scope)
+            for s in node.body:
+                out.extend(self._stmt(s, indent + 1, child, p, loop_stack=loop_stack))
+            out.append(pad + "}")
+            if node.orelse:
+                out[-1] += " else {"
+                child = set(scope)
+                for s in node.orelse:
+                    out.extend(self._stmt(s, indent + 1, child, p, loop_stack=loop_stack))
+                out.append(pad + "}")
+            return out
+        if isinstance(node, ast.While):
+            out = [f"{pad}while ({self._expr(node.test)}) {{"]
+            child = set(scope)
+            for s in node.body:
+                out.extend(self._stmt(s, indent + 1, child, p, loop_stack=(*loop_stack, "nested")))
+            out.append(pad + "}")
+            return out
+        if isinstance(node, ast.For):
+            if isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "range":
+                var = self._resolved_name(node.target)
+                start, stop, step = self._parse_range(node.iter, node, p)
+                step_value = self._literal_int(step)
+                if step_value == 0:
+                    raise CompileError("range() step cannot be zero.", node.lineno)
+                start_temp = self._new_temp("range_start")
+                stop_temp = self._new_temp("range_stop")
+                step_temp = self._new_temp("range_step")
+                iterator = self._new_temp("range_iter")
+                out = [
+                    f"{pad}int32_t {start_temp} = {self._expr(start)};",
+                    f"{pad}int32_t {stop_temp} = {self._expr(stop)};",
+                    f"{pad}int32_t {step_temp} = {self._expr(step)};",
+                ]
+                if step_value is None:
+                    out.append(f"{pad}if ({step_temp} == 0) _bj_numeric_fail();")
+                    cond = f"({step_temp} > 0 ? {iterator} < {stop_temp} : {iterator} > {stop_temp})"
+                else:
+                    cond = f"{iterator} {'<' if step_value > 0 else '>'} {stop_temp}"
+                out.extend([
+                    f"{pad}for (int32_t {iterator} = {start_temp}; {cond}; {iterator} = _bj_i32_add({iterator}, {step_temp})) {{",
+                    f"{pad}    {var} = {iterator};",
+                ])
+                child = set(scope); child.add(var)
+                for stmt in node.body:
+                    out.extend(self._stmt(stmt, indent + 1, child, p, loop_stack=(*loop_stack, "nested")))
+                out.append(pad + "}")
+                return out
+
+            enumerate_mode = isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "enumerate"
+            list_node = node.iter.args[0] if enumerate_mode else node.iter
+            if not isinstance(list_node, ast.Name):
+                raise InternalCompilerError("Fixed-list loop reached backend without a list name.", line=node.lineno)
+            list_type = self._typed.type_for_expr(list_node) if self._typed is not None else None
+            if list_type is None or list_type.kind != TypeKind.FIXED_LIST or list_type.length is None:
+                raise InternalCompilerError("Fixed-list loop reached backend without a fixed-list type.", line=node.lineno)
+            list_name = self._resolved_name(list_node)
+            iterator = self._new_temp("list_iter")
+            out = [f"{pad}for (int32_t {iterator} = 0; {iterator} < {list_type.length}; ++{iterator}) {{"]
+            child = set(scope)
+            if enumerate_mode:
+                if not isinstance(node.target, (ast.Tuple, ast.List)) or len(node.target.elts) != 2:
+                    raise InternalCompilerError("enumerate target shape changed after validation.", line=node.lineno)
+                idx_target, value_target = node.target.elts
+                idx_name = self._resolved_name(idx_target)
+                value_name = self._resolved_name(value_target)
+                if len(node.iter.args) == 2:
+                    start_temp = self._new_temp("enumerate_start")
+                    out.insert(0, f"{pad}int32_t {start_temp} = {self._expr(node.iter.args[1])};")
+                    out.append(f"{pad}    {idx_name} = _bj_i32_add({start_temp}, {iterator});")
+                else:
+                    out.append(f"{pad}    {idx_name} = {iterator};")
+                out.append(f"{pad}    {value_name} = {list_name}[{iterator}];")
+                child.update({idx_name, value_name})
+            else:
+                if not isinstance(node.target, ast.Name):
+                    raise InternalCompilerError("Fixed-list target shape changed after validation.", line=node.lineno)
+                value_name = self._resolved_name(node.target)
+                out.append(f"{pad}    {value_name} = {list_name}[{iterator}];")
+                child.add(value_name)
+            for stmt in node.body:
+                out.extend(self._stmt(stmt, indent + 1, child, p, loop_stack=(*loop_stack, "nested")))
+            out.append(pad + "}")
+            return out
+        raise CompileError(f"Cannot generate statement {type(node).__name__}.", getattr(node, "lineno", None))
+
+    def _numeric_helper_lines(self) -> list[str]:
+        """Emit checked numeric/Python-semantic helpers only when required."""
+        if self._numeric is None or self._typed is None:
+            return []
+        tree = self._resolved.frontend.tree if self._resolved is not None else None
+        need_add = need_sub = need_mul = need_neg = False
+        need_div = need_mod_i = need_mod_f = False
+        need_pwm = bool(self._numeric.checked_pwm_arguments)
+        need_time = bool(self._numeric.checked_time_thresholds)
+        need_float_to_int = False
+        need_round_i32 = need_round_f32_digits = need_round_i32_digits = False
+        need_abs_i = False
+        need_string_eq = False
+        need_list_index = False
+        need_runtime_fail = False
+
+        if tree is not None:
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Subscript):
+                    if self._literal_int(node.slice) is None:
+                        need_list_index = True
+                if isinstance(node, ast.For):
+                    if isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "range":
+                        need_add = True
+                    if isinstance(node.iter, ast.Call) and len(node.iter.args) == 3 and self._literal_int(node.iter.args[2]) is None:
+                        need_runtime_fail = True
+                elif isinstance(node, ast.AugAssign):
+                    try:
+                        target_type = self._typed.type_for_expr(node.target)
+                    except KeyError:
+                        target_type = None
+                    if isinstance(node.op, ast.Div):
+                        need_div = True
+                    elif isinstance(node.op, ast.Mod):
+                        if target_type is not None and target_type.kind == TypeKind.FLOAT:
+                            need_mod_f = True
+                        else:
+                            need_mod_i = True
+                    elif target_type is not None and target_type.kind == TypeKind.INT:
+                        need_add |= isinstance(node.op, ast.Add)
+                        need_sub |= isinstance(node.op, ast.Sub)
+                        need_mul |= isinstance(node.op, ast.Mult)
+                elif isinstance(node, ast.BinOp):
+                    if isinstance(node.op, ast.Div):
+                        need_div = True
+                    elif isinstance(node.op, ast.Mod):
+                        try:
+                            typ = self._typed.type_for_expr(node)
+                        except KeyError:
+                            typ = None
+                        need_mod_f |= typ is not None and typ.kind == TypeKind.FLOAT
+                        need_mod_i |= typ is None or typ.kind == TypeKind.INT
+                    elif self._numeric.int_expr_needs_runtime_check(node):
+                        need_add |= isinstance(node.op, ast.Add)
+                        need_sub |= isinstance(node.op, ast.Sub)
+                        need_mul |= isinstance(node.op, ast.Mult)
+                elif isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub) and self._numeric.int_expr_needs_runtime_check(node):
+                    need_neg = True
+                elif isinstance(node, ast.Compare):
+                    values = [node.left, *node.comparators]
+                    for a, b in zip(values, values[1:]):
+                        try:
+                            need_string_eq |= self._typed.type_for_expr(a).kind == TypeKind.STRING and self._typed.type_for_expr(b).kind == TypeKind.STRING
+                        except KeyError:
+                            pass
+                elif isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+                    if node.func.id == "sum" and node.args:
+                        try:
+                            list_type = self._typed.type_for_expr(node.args[0])
+                            need_add |= list_type.kind == TypeKind.FIXED_LIST and list_type.element_type is not None and list_type.element_type.kind == TypeKind.INT
+                        except KeyError:
+                            pass
+                    if node.func.id == "enumerate" and len(node.args) == 2:
+                        need_add = True
+                    if node.func.id == "int" and node.args:
+                        try:
+                            need_float_to_int |= self._typed.type_for_expr(node.args[0]).kind == TypeKind.FLOAT
+                        except KeyError:
+                            pass
+                    elif node.func.id == "round" and node.args:
+                        try:
+                            arg_kind = self._typed.type_for_expr(node.args[0]).kind
+                        except KeyError:
+                            arg_kind = None
+                        if len(node.args) == 1 and arg_kind == TypeKind.FLOAT:
+                            need_round_i32 = True
+                        elif len(node.args) == 2 and arg_kind == TypeKind.FLOAT:
+                            need_round_f32_digits = True
+                        elif len(node.args) == 2 and arg_kind == TypeKind.INT:
+                            need_round_i32_digits = True
+                    elif node.func.id == "abs" and node.args:
+                        try:
+                            need_abs_i |= self._typed.type_for_expr(node.args[0]).kind == TypeKind.INT
+                        except KeyError:
+                            pass
+
+        need_runtime_fail |= any((need_add, need_sub, need_mul, need_neg, need_div, need_mod_i, need_mod_f,
+                                  need_pwm, need_time, need_float_to_int, need_round_i32,
+                                  need_round_f32_digits, need_round_i32_digits, need_abs_i, need_list_index))
+        if not any((need_runtime_fail, need_string_eq)):
+            return []
+
+        out: list[str] = []
+        if need_runtime_fail:
+            out += [
+                "static void __attribute__((noinline, noreturn)) _bj_numeric_fail() {",
+                "    for (;;) { __asm__ __volatile__(\"\"); }",
+                "}",
+            ]
+        if need_list_index:
+            out += [
+                "static int32_t _bj_list_index(int32_t index, int32_t length) {",
+                "    if (index < 0 || index >= length) _bj_numeric_fail();",
+                "    return index;",
+                "}",
+            ]
+        if need_add:
+            out += [
+                "static int32_t _bj_i32_add(int32_t a, int32_t b) {",
+                "    int64_t r = (int64_t)a + (int64_t)b;",
+                "    if (r < (-2147483647LL - 1LL) || r > 2147483647LL) _bj_numeric_fail();",
+                "    return (int32_t)r;",
+                "}",
+            ]
+        if need_sub:
+            out += [
+                "static int32_t _bj_i32_sub(int32_t a, int32_t b) {",
+                "    int64_t r = (int64_t)a - (int64_t)b;",
+                "    if (r < (-2147483647LL - 1LL) || r > 2147483647LL) _bj_numeric_fail();",
+                "    return (int32_t)r;",
+                "}",
+            ]
+        if need_mul:
+            out += [
+                "static int32_t _bj_i32_mul(int32_t a, int32_t b) {",
+                "    int64_t r = (int64_t)a * (int64_t)b;",
+                "    if (r < (-2147483647LL - 1LL) || r > 2147483647LL) _bj_numeric_fail();",
+                "    return (int32_t)r;",
+                "}",
+            ]
+        if need_neg:
+            out += [
+                "static int32_t _bj_i32_neg(int32_t value) {",
+                "    if (value == (-2147483647L - 1L)) _bj_numeric_fail();",
+                "    return -value;",
+                "}",
+            ]
+        if need_div:
+            out += [
+                "static float _bj_true_div_f32(float a, float b) {",
+                "    if (b == 0.0f) _bj_numeric_fail();",
+                "    return a / b;",
+                "}",
+            ]
+        if need_mod_i:
+            out += [
+                "static int32_t _bj_mod_i32(int32_t a, int32_t b) {",
+                "    if (b == 0) _bj_numeric_fail();",
+                "    if (a == (-2147483647L - 1L) && b == -1) return 0;",
+                "    int32_t r = a % b;",
+                "    if (r != 0 && ((r < 0) != (b < 0))) r += b;",
+                "    return r;",
+                "}",
+            ]
+        if need_mod_f:
+            out += [
+                "static float _bj_mod_f32(float a, float b) {",
+                "    if (isnan(a) || isnan(b) || isinf(a) || isinf(b) || b == 0.0f) _bj_numeric_fail();",
+                "    float r = fmodf(a, b);",
+                "    if (r != 0.0f && ((r < 0.0f) != (b < 0.0f))) r += b;",
+                "    if (r == 0.0f) r = copysignf(0.0f, b);",
+                "    return r;",
+                "}",
+            ]
+        if need_pwm:
+            out += [
+                "static int32_t _bj_pwm_value(int32_t value) {",
+                "    if (value < 0 || value > 255) _bj_numeric_fail();",
+                "    return value;",
+                "}",
+            ]
+        if need_time:
+            out += [
+                "static uint32_t _bj_time_threshold(int32_t value) {",
+                "    if (value < 0) _bj_numeric_fail();",
+                "    return (uint32_t)value;",
+                "}",
+            ]
+        if need_float_to_int:
+            out += [
+                "static int32_t _bj_float_to_i32(float value) {",
+                "    if (isnan(value) || isinf(value) || value < -2147483648.0f || value >= 2147483648.0f) _bj_numeric_fail();",
+                "    return (int32_t)value;",
+                "}",
+            ]
+        if need_round_i32 or need_round_f32_digits:
+            out += [
+                "static float _bj_round_even_f32(float value) {",
+                "    float base = floorf(value);",
+                "    float frac = value - base;",
+                "    if (frac > 0.5f) return base + 1.0f;",
+                "    if (frac < 0.5f) return base;",
+                "    return (fmodf(fabsf(base), 2.0f) == 0.0f) ? base : (base + 1.0f);",
+                "}",
+            ]
+        if need_round_i32:
+            out += [
+                "static int32_t _bj_round_i32(float value) {",
+                "    if (isnan(value) || isinf(value) || value < -2147483648.0f || value >= 2147483648.0f) _bj_numeric_fail();",
+                "    float rounded = _bj_round_even_f32(value);",
+                "    if (rounded < -2147483648.0f || rounded >= 2147483648.0f) _bj_numeric_fail();",
+                "    return (int32_t)rounded;",
+                "}",
+            ]
+        if need_round_f32_digits:
+            out += [
+                "static uint64_t _bj_round_ratio_even_u64(uint64_t num, uint64_t den) {",
+                "    uint64_t q = num / den;",
+                "    uint64_t r = num % den;",
+                "    uint64_t twice = r * 2ULL;",
+                "    if (twice > den || (twice == den && (q & 1ULL))) ++q;",
+                "    return q;",
+                "}",
+                "static uint64_t _bj_round_pow2_even_u64(uint64_t num, uint8_t shift) {",
+                "    if (shift == 0) return num;",
+                "    if (shift >= 64) return 0;",
+                "    uint64_t q = num >> shift;",
+                "    uint64_t mask = (1ULL << shift) - 1ULL;",
+                "    uint64_t r = num & mask;",
+                "    uint64_t half = 1ULL << (shift - 1);",
+                "    if (r > half || (r == half && (q & 1ULL))) ++q;",
+                "    return q;",
+                "}",
+                "static float _bj_ratio_to_f32(bool negative, uint64_t num, uint32_t den) {",
+                "    union { uint32_t u; float f; } out;",
+                "    if (num == 0) { out.u = negative ? 0x80000000UL : 0UL; return out.f; }",
+                "    int16_t exponent = 0;",
+                "    if (num >= den) {",
+                "        uint64_t scaled_den = den;",
+                "        while (num >= (scaled_den << 1)) { scaled_den <<= 1; ++exponent; }",
+                "    } else {",
+                "        uint64_t scaled_num = num;",
+                "        while (scaled_num < den) { scaled_num <<= 1; --exponent; }",
+                "    }",
+                "    int16_t shift = 23 - exponent;",
+                "    uint64_t scaled_num = num;",
+                "    uint64_t scaled_den = den;",
+                "    if (shift >= 0) scaled_num <<= shift; else scaled_den <<= -shift;",
+                "    uint64_t significand = _bj_round_ratio_even_u64(scaled_num, scaled_den);",
+                "    if (significand == (1ULL << 24)) { significand >>= 1; ++exponent; }",
+                "    uint32_t exponent_bits = (uint32_t)(exponent + 127);",
+                "    if (exponent_bits == 0 || exponent_bits >= 255) _bj_numeric_fail();",
+                "    out.u = (negative ? 0x80000000UL : 0UL) | (exponent_bits << 23) | ((uint32_t)significand & 0x7FFFFFUL);",
+                "    return out.f;",
+                "}",
+                "static float _bj_round_f32_digits(float value, int8_t ndigits) {",
+                "    if (isnan(value) || isinf(value) || value == 0.0f) return value;",
+                "    union { float f; uint32_t u; } bits; bits.f = value;",
+                "    bool negative = (bits.u & 0x80000000UL) != 0;",
+                "    uint32_t exp_bits = (bits.u >> 23) & 0xFFUL;",
+                "    uint32_t fraction = bits.u & 0x7FFFFFUL;",
+                "    uint64_t mantissa; int16_t exponent2; int16_t unbiased;",
+                "    if (exp_bits == 0) { mantissa = fraction; exponent2 = -149; unbiased = -126; }",
+                "    else { mantissa = (1UL << 23) | fraction; unbiased = (int16_t)exp_bits - 127; exponent2 = unbiased - 23; }",
+                "    static const uint32_t p5[7] = {1UL, 5UL, 25UL, 125UL, 625UL, 3125UL, 15625UL};",
+                "    static const uint32_t p10[7] = {1UL, 10UL, 100UL, 1000UL, 10000UL, 100000UL, 1000000UL};",
+                "    if (ndigits >= 0) {",
+                "        if (unbiased >= 23) return value;",
+                "        uint8_t n = (uint8_t)ndigits;",
+                "        uint64_t mag = mantissa * (uint64_t)p5[n];",
+                "        int16_t shift2 = exponent2 + n;",
+                "        uint64_t rounded;",
+                "        if (shift2 >= 0) rounded = mag << shift2;",
+                "        else rounded = _bj_round_pow2_even_u64(mag, (uint8_t)(-shift2));",
+                "        return _bj_ratio_to_f32(negative, rounded, p10[n]);",
+                "    }",
+                "    uint8_t n = (uint8_t)(-ndigits);",
+                "    if (unbiased >= 43) return value;",
+                "    int16_t shift2 = exponent2 - n;",
+                "    uint64_t rounded;",
+                "    if (shift2 >= 0) {",
+                "        uint64_t numerator = mantissa << shift2;",
+                "        rounded = _bj_round_ratio_even_u64(numerator, p5[n]);",
+                "    } else {",
+                "        uint8_t down = (uint8_t)(-shift2);",
+                "        if (down >= 24) rounded = 0;",
+                "        else rounded = _bj_round_ratio_even_u64(mantissa, ((uint64_t)p5[n]) << down);",
+                "    }",
+                "    return _bj_ratio_to_f32(negative, rounded * (uint64_t)p10[n], 1UL);",
+                "}",
+            ]
+        if need_round_i32_digits:
+            out += [
+                "static int32_t _bj_round_i32_digits(int32_t value, int8_t ndigits) {",
+                "    if (ndigits >= 0) return value;",
+                "    static const int32_t p10[7] = {1L, 10L, 100L, 1000L, 10000L, 100000L, 1000000L};",
+                "    int64_t scale = p10[-ndigits];",
+                "    int64_t q = ((int64_t)value) / scale;",
+                "    int64_t r = ((int64_t)value) % scale;",
+                "    int64_t ar = r < 0 ? -r : r;",
+                "    int64_t twice = ar * 2LL;",
+                "    if (twice > scale || (twice == scale && (q % 2LL) != 0LL)) q += value < 0 ? -1LL : 1LL;",
+                "    int64_t result = q * scale;",
+                "    if (result < (-2147483647LL - 1LL) || result > 2147483647LL) _bj_numeric_fail();",
+                "    return (int32_t)result;",
+                "}",
+            ]
+        if need_abs_i:
+            out += [
+                "static int32_t _bj_i32_abs(int32_t value) {",
+                "    if (value == (-2147483647L - 1L)) _bj_numeric_fail();",
+                "    return value < 0 ? -value : value;",
+                "}",
+            ]
+        if need_string_eq:
+            out += [
+                "static bool _bj_str_eq(const char* a, const char* b) {",
+                "    while (*a && *b && *a == *b) { ++a; ++b; }",
+                "    return *a == *b;",
+                "}",
+            ]
+        return out
+
+    def _output_helper_lines(self) -> list[str]:
+        """Compiler-owned Python output helpers, emitted only when required."""
+        if not self._needs_python_float_formatter():
+            return []
+        return [
+            "static void _bj_print_py_float(Print& out, float value) {",
+            "    if (isnan(value)) { out.print(F(\"nan\")); return; }",
+            "    if (isinf(value)) { out.print(value < 0.0f ? F(\"-inf\") : F(\"inf\")); return; }",
+            "    if (value == 0.0f) {",
+            "        union { float f; uint32_t u; } bits; bits.f = value;",
+            "        out.print((bits.u & 0x80000000UL) ? F(\"-0.0\") : F(\"0.0\"));",
+            "        return;",
+            "    }",
+            "    char scientific[20];",
+            "    dtostre(value, scientific, 8, 0);  // 9 significant digits: enough to round-trip float32.",
+            "    const char* p = scientific;",
+            "    char result[32]; char* w = result;",
+            "    if (*p == '-') *w++ = *p++;",
+            "    char digits[10]; uint8_t count = 0;",
+            "    if (*p) digits[count++] = *p++;",
+            "    if (*p == '.') ++p;",
+            "    while (*p && *p != 'e' && *p != 'E' && count < 9) digits[count++] = *p++;",
+            "    while (count > 1 && digits[count - 1] == '0') --count;",
+            "    if (*p == 'e' || *p == 'E') ++p;",
+            "    bool exp_negative = false;",
+            "    if (*p == '+' || *p == '-') { exp_negative = (*p == '-'); ++p; }",
+            "    int16_t exponent = 0;",
+            "    while (*p >= '0' && *p <= '9') { exponent = (int16_t)(exponent * 10 + (*p++ - '0')); }",
+            "    if (exp_negative) exponent = -exponent;",
+            "    if (exponent >= -4 && exponent < 16) {",
+            "        int16_t decimal_pos = exponent + 1;",
+            "        if (decimal_pos <= 0) {",
+            "            *w++ = '0'; *w++ = '.';",
+            "            for (int16_t i = 0; i < -decimal_pos; ++i) *w++ = '0';",
+            "            for (uint8_t i = 0; i < count; ++i) *w++ = digits[i];",
+            "        } else {",
+            "            for (int16_t i = 0; i < decimal_pos; ++i) *w++ = (i < count) ? digits[i] : '0';",
+            "            if (decimal_pos < count) {",
+            "                *w++ = '.';",
+            "                for (uint8_t i = (uint8_t)decimal_pos; i < count; ++i) *w++ = digits[i];",
+            "            } else {",
+            "                *w++ = '.'; *w++ = '0';",
+            "            }",
+            "        }",
+            "    } else {",
+            "        *w++ = digits[0];",
+            "        if (count > 1) { *w++ = '.'; for (uint8_t i = 1; i < count; ++i) *w++ = digits[i]; }",
+            "        *w++ = 'e';",
+            "        int16_t e = exponent;",
+            "        if (e < 0) { *w++ = '-'; e = -e; } else { *w++ = '+'; }",
+            "        char expbuf[6]; uint8_t n = 0;",
+            "        do { expbuf[n++] = (char)('0' + (e % 10)); e /= 10; } while (e && n < sizeof(expbuf));",
+            "        while (n) *w++ = expbuf[--n];",
+            "    }",
+            "    *w = '\\0';",
+            "    out.print(result);",
+            "}",
+        ]
+
+    def _needs_python_float_formatter(self) -> bool:
+        if self._resolved is None or self._typed is None:
+            return False
+
+        def fstring_needs(node: ast.JoinedStr) -> bool:
+            for part in node.values:
+                if not isinstance(part, ast.FormattedValue):
+                    continue
+                if part.format_spec is not None:
+                    continue
+                try:
+                    if self._typed.type_for_expr(part.value).kind == TypeKind.FLOAT:
+                        return True
+                except KeyError:
+                    pass
+            return False
+
+        for node in ast.walk(self._resolved.frontend.tree):
+            if not isinstance(node, ast.Call):
+                continue
+            is_python_print = isinstance(node.func, ast.Name) and node.func.id == "print"
+            is_output_method = (
+                isinstance(node.func, ast.Attribute)
+                and node.func.attr in {"print", "println"}
+            )
+            if not (is_python_print or is_output_method):
+                continue
+            for arg in node.args:
+                if isinstance(arg, ast.JoinedStr):
+                    if fstring_needs(arg):
+                        return True
+                elif is_python_print:
+                    try:
+                        if self._typed.type_for_expr(arg).kind == TypeKind.FLOAT:
+                            return True
+                    except KeyError:
+                        pass
+        return False
+
+    def _new_temp(self, hint: str) -> str:
+        self._temp_counter += 1
+        return f"_bj_tmp_{hint}_{self._temp_counter:04d}"
+
+    def _symbols_with_storage(self, storage: StorageClass) -> list:
+        if self._flow is None:
+            return []
+        symbols = [fact.symbol for fact in self._flow.symbol_facts.values() if fact.storage == storage]
+        return sorted(symbols, key=lambda x: (x.declaration_line or 10**9, x.symbol_id.value))
+
+    def _module_predeclared_cpp_names(self, *storages: StorageClass) -> set[str]:
+        if self._flow is None:
+            return set()
+        accepted = set(storages)
+        return {
+            fact.symbol.cpp_name for fact in self._flow.symbol_facts.values()
+            if fact.symbol.scope_name == "<module>" and fact.storage in accepted
+        }
+
+    def _cpp_type_for_symbol(self, symbol) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during code generation.")
+        return self._typed.type_for_symbol(symbol).cpp_type
+
+    def _declaration_type(self, symbol) -> str:
+        """Formal Step-7 storage type supplied by the type phase."""
+        return self._cpp_type_for_symbol(symbol)
+
+    def _first_assignment_expr(self, symbol):
+        if self._resolved is None:
+            return None
+        found = None
+
+        class Finder(ast.NodeVisitor):
+            def visit_FunctionDef(inner_self, node: ast.FunctionDef):
+                nonlocal found
+                # Search only the owning function for function-local symbols;
+                # skip functions when looking for module storage.
+                if symbol.scope_name == "<module>":
+                    return
+                if node.name != symbol.scope_name:
+                    return
+                inner_self.generic_visit(node)
+
+            def visit_Assign(inner_self, node: ast.Assign):
+                nonlocal found
+                if found is not None:
+                    return
+                for target in node.targets:
+                    pairs = [(target, node.value)]
+                    if isinstance(target, (ast.Tuple, ast.List)) and isinstance(node.value, (ast.Tuple, ast.List)):
+                        pairs = list(zip(target.elts, node.value.elts))
+                    for t, value in pairs:
+                        if isinstance(t, ast.Name):
+                            try:
+                                sym = self._resolved.symbol_for_name(t)
+                            except KeyError:
+                                continue
+                            if sym.symbol_id == symbol.symbol_id:
+                                found = value
+                                return
+                inner_self.generic_visit(node.value)
+
+            def visit_For(inner_self, node: ast.For):
+                nonlocal found
+                if found is None and isinstance(node.target, ast.Name):
+                    try:
+                        sym = self._resolved.symbol_for_name(node.target)
+                    except KeyError:
+                        sym = None
+                    if sym is not None and sym.symbol_id == symbol.symbol_id:
+                        found = ast.Constant(value=0)
+                        return
+                inner_self.generic_visit(node)
+
+        Finder().visit(self._resolved.frontend.tree)
+        return found
+
+    def _serial_print(self, call: ast.Call, indent: int) -> list[str]:
+        """Lower Python print() with Python evaluation/formatting semantics."""
+        pad = "    " * indent
+        preludes: list[str] = []
+        parts: list[_OutputPart] = []
+        for index, arg in enumerate(call.args):
+            if index:
+                parts.append(_OutputPart(literal=" "))
+            arg_prelude, arg_parts = self._prepare_python_output_arg(arg)
+            preludes.extend(arg_prelude)
+            parts.extend(arg_parts)
+
+        out = [pad + line for line in preludes]
+        for part in parts:
+            out.extend(self._emit_python_output_part("Serial", part, indent, lcd_mode=False))
+        # Python print() always emits exactly one final newline, including print().
+        out.append(pad + "Serial.println();")
+        return out
+
+    def _explicit_output_stmt(self, call: ast.Call, indent: int) -> list[str] | None:
+        """Special output lowering for flash literals and Python f-strings.
+
+        Plain explicit Serial/LCD numeric calls remain Arduino-compatible and
+        therefore fall back to the ordinary API emitter.  Only f-strings need
+        Python formatting, while direct string literals can safely use F().
+        """
+        if not isinstance(call.func, ast.Attribute) or not isinstance(call.func.value, ast.Name):
+            return None
+        owner_source = call.func.value.id
+        method = call.func.attr
+        if method not in {"print", "println"}:
+            return None
+        owner = self._expr(call.func.value)
+        lcd_mode = self._objects.get(owner_source) == "LiquidCrystal_I2C"
+        pad = "    " * indent
+
+        if len(call.args) == 1 and isinstance(call.args[0], ast.Constant) and isinstance(call.args[0].value, str):
+            literal = self._flash_literal(call.args[0].value, lcd_mode=lcd_mode)
+            return [f"{pad}{owner}.{method}({literal});"]
+
+        if len(call.args) == 1 and isinstance(call.args[0], ast.JoinedStr):
+            preludes, parts = self._prepare_python_output_arg(call.args[0])
+            out = [pad + line for line in preludes]
+            for part in parts:
+                out.extend(self._emit_python_output_part(owner, part, indent, lcd_mode=lcd_mode))
+            if method == "println":
+                out.append(f"{pad}{owner}.println();")
+            return out
+        return None
+
+    def _prepare_python_output_arg(self, node: ast.AST) -> tuple[list[str], list[_OutputPart]]:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during output lowering.")
+        if isinstance(node, ast.JoinedStr):
+            preludes: list[str] = []
+            parts: list[_OutputPart] = []
+            for item in node.values:
+                if isinstance(item, ast.Constant) and isinstance(item.value, str):
+                    if item.value:
+                        parts.append(_OutputPart(literal=item.value))
+                    continue
+                if not isinstance(item, ast.FormattedValue):
+                    raise InternalCompilerError("Unexpected f-string part reached output lowering.", line=getattr(item, "lineno", None))
+                precision = self._fstring_precision(item)
+                prelude, part = self._prepare_python_output_value(item.value, precision=precision)
+                preludes.extend(prelude)
+                parts.append(part)
+            return preludes, parts
+
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            return [], [_OutputPart(literal=node.value)]
+        prelude, part = self._prepare_python_output_value(node, precision=None)
+        return prelude, [part]
+
+    def _prepare_python_output_value(self, node: ast.AST, *, precision: int | None) -> tuple[list[str], _OutputPart]:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during output lowering.")
+        typ = self._typed.type_for_expr(node)
+        if typ.kind not in {TypeKind.BOOL, TypeKind.INT, TypeKind.TIME_U32, TypeKind.FLOAT, TypeKind.STRING}:
+            raise InternalCompilerError(
+                f"Non-printable type {typ.kind.value} reached output lowering.",
+                line=getattr(node, "lineno", None),
+            )
+        expr = self._expr(node)
+        # Constants are side-effect free and immutable, so they need no temp.
+        # Everything else is captured before *any* output bytes are emitted.
+        if isinstance(node, ast.Constant):
+            return [], _OutputPart(expression=expr, type_kind=typ.kind, precision=precision)
+        temp = self._new_temp("print_arg")
+        return [f"{typ.cpp_type} {temp} = {expr};"], _OutputPart(
+            expression=temp,
+            type_kind=typ.kind,
+            precision=precision,
+        )
+
+    def _emit_python_output_part(self, sink: str, part: _OutputPart, indent: int, *, lcd_mode: bool) -> list[str]:
+        pad = "    " * indent
+        if part.literal is not None:
+            return [f"{pad}{sink}.print({self._flash_literal(part.literal, lcd_mode=lcd_mode)});"]
+        if part.expression is None or part.type_kind is None:
+            raise InternalCompilerError("Malformed Python output part reached backend.")
+        expr = part.expression
+        if part.precision is not None:
+            # Deliberate float cast prevents Arduino Print::print(long, base)
+            # from interpreting .Nf precision as an integer number base.
+            return [f"{pad}{sink}.print((float)({expr}), {part.precision});"]
+        if part.type_kind == TypeKind.BOOL:
+            return [f"{pad}if ({expr}) {sink}.print(F(\"True\")); else {sink}.print(F(\"False\"));"]
+        if part.type_kind == TypeKind.INT:
+            return [f"{pad}{sink}.print((int32_t)({expr}));"]
+        if part.type_kind == TypeKind.TIME_U32:
+            return [f"{pad}{sink}.print((uint32_t)({expr}));"]
+        if part.type_kind == TypeKind.FLOAT:
+            return [f"{pad}_bj_print_py_float({sink}, (float)({expr}));"]
+        if part.type_kind == TypeKind.STRING:
+            return [f"{pad}{sink}.print({expr});"]
+        raise InternalCompilerError("Unsupported Python output type reached backend.")
+
+    @staticmethod
+    def _fstring_precision(node: ast.FormattedValue) -> int | None:
+        if node.format_spec is None:
+            return None
+        if not isinstance(node.format_spec, ast.JoinedStr):
+            raise InternalCompilerError("Validated f-string format changed before backend lowering.")
+        text = "".join(
+            item.value for item in node.format_spec.values
+            if isinstance(item, ast.Constant) and isinstance(item.value, str)
+        )
+        if text.startswith(".") and text.endswith("f") and text[1:-1].isdigit():
+            return int(text[1:-1])
+        raise InternalCompilerError("Unsupported f-string format reached backend after validation.")
+
+    def _flash_literal(self, text: str, *, lcd_mode: bool = False) -> str:
+        return f"F({self._cpp_string_literal(text, lcd_mode=lcd_mode)})"
+
+    @staticmethod
+    def _cpp_string_literal(text: str, *, lcd_mode: bool = False) -> str:
+        data = bytearray()
+        if lcd_mode:
+            for ch in text:
+                code = ord(ch)
+                if 0x20 <= code <= 0x7E:
+                    data.append(code)
+                elif ch == "°":
+                    data.append(0xDF)
+                else:
+                    raise InternalCompilerError("Unsupported LCD character reached backend after target validation.")
+        else:
+            data.extend(text.encode("utf-8"))
+
+        pieces: list[str] = []
+        for byte in data:
+            if byte == 0x5C:
+                pieces.append("\\\\")
+            elif byte == 0x22:
+                pieces.append('\\"')
+            elif byte == 0x0A:
+                pieces.append("\\n")
+            elif byte == 0x0D:
+                pieces.append("\\r")
+            elif byte == 0x09:
+                pieces.append("\\t")
+            elif 0x20 <= byte <= 0x7E:
+                pieces.append(chr(byte))
+            else:
+                # Fixed-width octal escapes cannot consume following hex chars.
+                pieces.append(f"\\{byte:03o}")
+        return '"' + "".join(pieces) + '"'
+
+    # ---------- semantic expression helpers ----------
+    @staticmethod
+    def _expr_has_effects(node: ast.AST) -> bool:
+        return any(isinstance(x, ast.Call) for x in ast.walk(node))
+
+    def _cpp_expr_type(self, node: ast.AST) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during semantic lowering.")
+        return self._typed.type_for_expr(node).cpp_type
+
+    def _ordered_call(self, node: ast.Call, callee: str, args: list[str]) -> str:
+        """Preserve Python left-to-right argument evaluation for effectful args."""
+        if len(node.args) <= 1 or not any(self._expr_has_effects(a) for a in node.args):
+            return f"{callee}({', '.join(args)})"
+        decls: list[str] = []
+        names: list[str] = []
+        for arg_node, arg_expr in zip(node.args, args):
+            name = self._new_temp("arg")
+            names.append(name)
+            decls.append(f"{self._cpp_expr_type(arg_node)} {name} = {arg_expr};")
+        ret = self._typed.type_for_expr(node) if self._typed is not None else None
+        call = f"{callee}({', '.join(names)})"
+        if ret is not None and ret.kind == TypeKind.VOID:
+            return "([&]() { " + " ".join(decls) + f" {call}; }}())"
+        return "([&]() -> " + (ret.cpp_type if ret is not None else "auto") + " { " + " ".join(decls) + f" return {call}; }}())"
+
+    def _binary_expr(self, node: ast.BinOp) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during binary lowering.")
+        typ = self._typed.type_for_expr(node)
+        left_expr = self._expr(node.left)
+        right_expr = self._expr(node.right)
+
+        def operation(left: str, right: str) -> str:
+            if typ.kind == TypeKind.TIME_U32 and isinstance(node.op, ast.Sub):
+                return f"((uint32_t)({left}) - (uint32_t)({right}))"
+            if isinstance(node.op, ast.Div):
+                return f"_bj_true_div_f32((float)({left}), (float)({right}))"
+            if isinstance(node.op, ast.Mod):
+                if typ.kind == TypeKind.FLOAT:
+                    return f"_bj_mod_f32((float)({left}), (float)({right}))"
+                return f"_bj_mod_i32({left}, {right})"
+            if typ.kind == TypeKind.INT and self._numeric is not None and self._numeric.int_expr_needs_runtime_check(node):
+                helper = {ast.Add: "_bj_i32_add", ast.Sub: "_bj_i32_sub", ast.Mult: "_bj_i32_mul"}.get(type(node.op))
+                if helper is not None:
+                    return f"{helper}({left}, {right})"
+            op = {ast.Add: "+", ast.Sub: "-", ast.Mult: "*"}[type(node.op)]
+            return f"({left} {op} {right})"
+
+        if self._expr_has_effects(node.left) or self._expr_has_effects(node.right):
+            ltmp = self._new_temp("lhs")
+            rtmp = self._new_temp("rhs")
+            ltype = self._cpp_expr_type(node.left)
+            rtype = self._cpp_expr_type(node.right)
+            return (
+                f"([&]() -> {typ.cpp_type} {{ {ltype} {ltmp} = {left_expr}; "
+                f"{rtype} {rtmp} = {right_expr}; return {operation(ltmp, rtmp)}; }}())"
+            )
+        return operation(left_expr, right_expr)
+
+    def _comparison_operand(self, left_node: ast.AST, right_node: ast.AST, opnode: ast.cmpop, left: str, right: str) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during comparison lowering.")
+        lt = self._typed.type_for_expr(left_node)
+        rt = self._typed.type_for_expr(right_node)
+        if lt.kind == TypeKind.STRING and rt.kind == TypeKind.STRING:
+            eq = f"_bj_str_eq({left}, {right})"
+            return eq if isinstance(opnode, ast.Eq) else f"(!{eq})"
+        if self._numeric is not None:
+            if lt.kind == TypeKind.TIME_U32 and rt.kind == TypeKind.INT:
+                right = f"_bj_time_threshold({right})" if self._numeric.time_threshold_needs_runtime_check(right_node) else f"((uint32_t)({right}))"
+            elif rt.kind == TypeKind.TIME_U32 and lt.kind == TypeKind.INT:
+                left = f"_bj_time_threshold({left})" if self._numeric.time_threshold_needs_runtime_check(left_node) else f"((uint32_t)({left}))"
+        op = {ast.Eq: "==", ast.NotEq: "!=", ast.Lt: "<", ast.LtE: "<=", ast.Gt: ">", ast.GtE: ">="}[type(opnode)]
+        return f"({left} {op} {right})"
+
+    def _comparison_expr(self, node: ast.Compare) -> str:
+        # C++ does not guarantee Python's comparison operand evaluation order.
+        # Materialize operands sequentially and stop before evaluating later
+        # operands when an earlier comparison is false.
+        values = [node.left, *node.comparators]
+        temp_names = [self._new_temp("cmp") for _ in values]
+        pieces: list[str] = [f"{self._cpp_expr_type(values[0])} {temp_names[0]} = {self._expr(values[0])};"]
+        for index, (opnode, right_node) in enumerate(zip(node.ops, node.comparators)):
+            pieces.append(f"{self._cpp_expr_type(right_node)} {temp_names[index + 1]} = {self._expr(right_node)};")
+            cmp_expr = self._comparison_operand(values[index], right_node, opnode, temp_names[index], temp_names[index + 1])
+            pieces.append(f"if (!({cmp_expr})) return false;")
+        pieces.append("return true;")
+        return "([&]() -> bool { " + " ".join(pieces) + " }())"
+
+    def _minmax_expr(self, node: ast.Call, *, want_min: bool) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during min/max lowering.")
+        result_type = self._typed.type_for_expr(node).cpp_type
+        temp_names: list[str] = []
+        parts: list[str] = []
+        for arg in node.args:
+            name = self._new_temp("minmax_arg")
+            temp_names.append(name)
+            parts.append(f"{self._cpp_expr_type(arg)} {name} = {self._expr(arg)};")
+        result = self._new_temp("minmax")
+        parts.append(f"{result_type} {result} = {temp_names[0]};")
+        op = "<" if want_min else ">"
+        for name in temp_names[1:]:
+            parts.append(f"if ({name} {op} {result}) {result} = {name};")
+        parts.append(f"return {result};")
+        return f"([&]() -> {result_type} {{ " + " ".join(parts) + " }())"
+
+    # ---------- expressions ----------
+    def _expr(self, node: ast.AST) -> str:
+        if isinstance(node, ast.Constant):
+            if node.value is True: return "true"
+            if node.value is False: return "false"
+            if node.value is None: raise CompileError("None is not supported in Arduino expressions.", node.lineno)
+            if isinstance(node.value, str):
+                return self._cpp_string_literal(node.value)
+            return repr(node.value)
+        if isinstance(node, ast.Name):
+            return self._resolved_name(node)
+        if isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Attribute):
+                owner = self._expr(node.func.value)
+                arg_values = [self._expr(a) for a in node.args]
+                return self._ordered_call(node, f"{owner}.{node.func.attr}", arg_values)
+            if not isinstance(node.func, ast.Name):
+                raise CompileError("Unsupported call form.", node.lineno)
+            name = node.func.id
+            args = [self._expr(a) for a in node.args]
+            if name == "round":
+                arg_type = self._typed.type_for_expr(node.args[0]) if self._typed is not None else None
+                if len(args) == 1:
+                    if arg_type is not None and arg_type.kind == TypeKind.INT:
+                        return args[0]
+                    return f"_bj_round_i32((float)({args[0]}))"
+                ndigits = self._literal_int(node.args[1])
+                if ndigits is None:
+                    raise InternalCompilerError("round() ndigits reached code generation without a compile-time value.", line=node.lineno)
+                if arg_type is not None and arg_type.kind == TypeKind.INT:
+                    return f"_bj_round_i32_digits({args[0]}, {ndigits})"
+                return f"_bj_round_f32_digits((float)({args[0]}), {ndigits})"
+            if name == "min":
+                return self._minmax_expr(node, want_min=True)
+            if name == "max":
+                return self._minmax_expr(node, want_min=False)
+            if name == "int":
+                if self._typed is not None and node.args:
+                    arg_type = self._typed.type_for_expr(node.args[0])
+                    if arg_type.kind == TypeKind.FLOAT:
+                        return f"_bj_float_to_i32((float)({args[0]}))"
+                return f"((int32_t)({args[0]}))"
+            if name == "float": return f"((float)({args[0]}))"
+            if name == "bool": return f"((bool)({args[0]}))"
+            if name == "abs" and self._typed is not None and node.args:
+                if self._typed.type_for_expr(node.args[0]).kind == TypeKind.INT:
+                    return f"_bj_i32_abs({args[0]})"
+                return f"fabsf((float)({args[0]}))"
+            if name == "len" and node.args and self._typed is not None:
+                list_type = self._typed.type_for_expr(node.args[0])
+                if list_type.kind != TypeKind.FIXED_LIST or list_type.length is None:
+                    raise InternalCompilerError("len() reached backend without fixed-list type.", line=node.lineno)
+                return str(list_type.length)
+            if name == "sum" and node.args and self._typed is not None:
+                arg = node.args[0]
+                if not isinstance(arg, ast.Name):
+                    raise InternalCompilerError("sum() reached backend without a fixed-list name.", line=node.lineno)
+                list_type = self._typed.type_for_expr(arg)
+                if list_type.kind != TypeKind.FIXED_LIST or list_type.length is None or list_type.element_type is None:
+                    raise InternalCompilerError("sum() reached backend without fixed-list type.", line=node.lineno)
+                list_name = self._resolved_name(arg)
+                idx = self._new_temp("sum_i")
+                acc = self._new_temp("sum_acc")
+                if list_type.element_type.kind == TypeKind.INT:
+                    return f"([&]() -> int32_t {{ int32_t {acc} = 0; for (int32_t {idx} = 0; {idx} < {list_type.length}; ++{idx}) {acc} = _bj_i32_add({acc}, {list_name}[{idx}]); return {acc}; }}())"
+                return f"([&]() -> float {{ float {acc} = 0.0f; for (int32_t {idx} = 0; {idx} < {list_type.length}; ++{idx}) {acc} += {list_name}[{idx}]; return {acc}; }}())"
+            if name == "analogWrite" and len(node.args) >= 2 and self._numeric is not None:
+                if self._numeric.pwm_arg_needs_runtime_check(node.args[1]):
+                    args[1] = f"_bj_pwm_value({args[1]})"
+            callee = self._resolved_name(node.func)
+            return self._ordered_call(node, callee, args)
+        if isinstance(node, ast.UnaryOp):
+            operand = self._expr(node.operand)
+            if isinstance(node.op, ast.USub):
+                if isinstance(node.operand, ast.Constant) and node.operand.value == 2**31:
+                    return "(-2147483647L - 1L)"
+                if self._numeric is not None and self._numeric.int_expr_needs_runtime_check(node):
+                    return f"_bj_i32_neg({operand})"
+                return f"(-{operand})"
+            return f"(!{operand})"
+        if isinstance(node, ast.BinOp):
+            return self._binary_expr(node)
+        if isinstance(node, ast.Compare):
+            return self._comparison_expr(node)
+        if isinstance(node, ast.BoolOp):
+            op = " && " if isinstance(node.op, ast.And) else " || "
+            return "(" + op.join(self._expr(v) for v in node.values) + ")"
+        if isinstance(node, ast.IfExp):
+            return f"({self._expr(node.test)} ? {self._expr(node.body)} : {self._expr(node.orelse)})"
+        if isinstance(node, ast.List):
+            return "{" + ", ".join(self._expr(x) for x in node.elts) + "}"
+        if isinstance(node, ast.Subscript):
+            return self._subscript_lvalue(node)
+        raise CompileError(f"Cannot generate expression {type(node).__name__}.", getattr(node, "lineno", None))
+
+    def _declaration_line(self, symbol) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during declaration generation.")
+        typ = self._typed.type_for_symbol(symbol)
+        if typ.kind == TypeKind.FIXED_LIST:
+            if typ.element_type is None or typ.length is None:
+                raise InternalCompilerError("Incomplete fixed-list type reached declaration generation.")
+            return f"{typ.element_type.cpp_type} {symbol.cpp_name}[{typ.length}];"
+        return f"{typ.cpp_type} {symbol.cpp_name};"
+
+    def _subscript_lvalue(self, node: ast.Subscript) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during list indexing.")
+        if not isinstance(node.value, ast.Name):
+            raise InternalCompilerError("V1 fixed-list indexing reached backend without a list name.", line=getattr(node, "lineno", None))
+        list_type = self._typed.type_for_expr(node.value)
+        if list_type.kind != TypeKind.FIXED_LIST or list_type.length is None:
+            raise InternalCompilerError("Indexed value is not a fixed list.", line=getattr(node, "lineno", None))
+        name = self._resolved_name(node.value)
+        literal = self._literal_int(node.slice)
+        if literal is not None:
+            return f"{name}[{literal}]"
+        return f"{name}[_bj_list_index({self._expr(node.slice)}, {list_type.length})]"
+
+    def _infer_expr_type(self, node: ast.AST) -> str:
+        if self._typed is None:
+            raise InternalCompilerError("Typed analysis is unavailable during expression generation.")
+        try:
+            return self._typed.type_for_expr(node).cpp_type
+        except KeyError:
+            raise InternalCompilerError(
+                "An expression reached code generation without a resolved type.",
+                line=getattr(node, "lineno", None),
+                details=type(node).__name__,
+            ) from None
+
+    # ---------- helpers ----------
+    @staticmethod
+    def _literal_python_value(value: ast.AST):
+        if isinstance(value, ast.Constant): return value.value
+        if isinstance(value, ast.UnaryOp) and isinstance(value.op, ast.USub) and isinstance(value.operand, ast.Constant):
+            return -value.operand.value
+        return None
+
+    def _literal_pin(self, node: ast.AST) -> int | None:
+        if isinstance(node, ast.Constant) and isinstance(node.value, int): return node.value
+        if isinstance(node, ast.Name):
+            if node.id in self.board.analog_aliases: return self.board.analog_aliases[node.id]
+            v = self._global_values.get(node.id)
+            return v if isinstance(v, int) else None
+        return None
+
+    def _parse_range(self, node: ast.AST, owner: ast.AST, p: Program):
+        if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name) or node.func.id != "range":
+            raise CompileError("V1 for-loops use 'for x in range(...)'.", getattr(owner, "lineno", None))
+        if node.keywords or not (1 <= len(node.args) <= 3):
+            raise CompileError("range() accepts 1 to 3 positional values.", getattr(owner, "lineno", None))
+        zero, one = ast.Constant(value=0), ast.Constant(value=1)
+        if len(node.args) == 1: start, stop, step = zero, node.args[0], one
+        elif len(node.args) == 2: start, stop, step = node.args[0], node.args[1], one
+        else: start, stop, step = node.args
+        for expr in (start, stop, step): self._validate_expr(expr, p)
+        return start, stop, step
+
+    @staticmethod
+    def _literal_int(node: ast.AST) -> int | None:
+        if isinstance(node, ast.Constant) and isinstance(node.value, int) and not isinstance(node.value, bool): return node.value
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub) and isinstance(node.operand, ast.Constant) and isinstance(node.operand.value, int):
+            return -node.operand.value
+        return None