Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/target.py

@@ -0,0 +1,1631 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import ast
+from typing import Iterable
+
+from .api_registry import CONSTANT_VALUES, DEPENDENCIES, HARDWARE_CLASSES, SINGLETONS, CORE_FUNCTIONS
+from . import device_packs as _packs
+from .board import BoardProfile
+from .errors import CompileError, HardwareError, InternalCompilerError, UnsupportedFeatureError
+from .flow import StorageClass
+from .ir import (
+    IRModule, IRStmt, IRExpr, IRConstant, IRLoad, IRListLiteral, IRIndex, IRUnary, IRUnaryOp, IRBinary, IRBinaryOp,
+    IRCompareChain, IRBool, IRConditional, IRCall, IRCallKind, IRFormatString,
+    IRStore, IRIndexStore, IRAugStore, IRExprStmt, IRPrint, IRIf, IRWhile, IRRangeLoop,
+    IRFixedListLoop, IRReturn, IRObjectDecl,
+)
+from .numeric import NumericAnalysis
+from .source import SourceSpan
+from .typesys import TypeKind, BarmajaType
+
+
+@dataclass(frozen=True)
+class TargetDiagnostic:
+    category: str
+    code: str
+    severity: str
+    message: str
+    source: str | None = None
+    span: SourceSpan | None = None
+    hint: str | None = None
+    related: tuple[SourceSpan, ...] = ()
+
+
+@dataclass(frozen=True)
+class TargetPlan:
+    board: BoardProfile
+    ir_module: IRModule
+    includes: tuple[str, ...]
+    dependency_ids: tuple[str, ...]
+    setup_hooks: tuple[str, ...]
+    resolved_serial_baud: int | None
+    diagnostics: tuple[TargetDiagnostic, ...]
+    static_sram_estimate: int
+    resources: frozenset[str]
+    lifecycle_facts: tuple[str, ...]
+    # Compile-time integer value of each hardware-constructor argument, keyed by
+    # object symbol id. Constructors run before setup(), so the backend must
+    # emit these proven values instead of references to setup-time variables.
+    object_arg_values: tuple[tuple[object, tuple[int | None, ...]], ...] = ()
+    # True when the program can WRITE text to the USB Serial port (Python print(),
+    # Serial.print/println/write). Used by the PC-side monitor; Serial.begin alone
+    # or Serial.available()/read() do not need a PC console.
+    serial_output: bool = False
+
+    @property
+    def warnings(self) -> tuple[TargetDiagnostic, ...]:
+        return tuple(d for d in self.diagnostics if d.severity == "warning")
+
+
+@dataclass
+class _LifeState:
+    dht_begun: set[object] = field(default_factory=set)
+    lcd_inited: set[object] = field(default_factory=set)
+    servo_attached: set[object] = field(default_factory=set)
+    modules_started: set[object] = field(default_factory=set)
+    wire_begun: bool = False
+    serial_begun: bool = False
+
+    def copy(self) -> "_LifeState":
+        return _LifeState(set(self.dht_begun), set(self.lcd_inited), set(self.servo_attached), set(self.modules_started), self.wire_begun, self.serial_begun)
+
+    @staticmethod
+    def intersect(a: "_LifeState", b: "_LifeState") -> "_LifeState":
+        return _LifeState(
+            a.dht_begun & b.dht_begun,
+            a.lcd_inited & b.lcd_inited,
+            a.servo_attached & b.servo_attached,
+            a.modules_started & b.modules_started,
+            a.wire_begun and b.wire_begun,
+            a.serial_begun and b.serial_begun,
+        )
+
+
+class TargetAnalyzer:
+    def __init__(self, ir_module: IRModule, numeric: NumericAnalysis, board: BoardProfile):
+        self.ir = ir_module
+        self.numeric = numeric
+        self.board = board
+        self._diagnostics: list[TargetDiagnostic] = []
+        self._diag_keys: set[tuple] = set()
+        self._dependencies: set[str] = set()
+        self._includes: set[str] = {"Arduino.h"}
+        self._resources: set[str] = set()
+        self._lifecycle_facts: set[str] = set()
+        self._functions = {fn.symbol.symbol_id: fn for fn in ir_module.functions}
+        self._storages = {d.symbol.symbol_id: d for d in ir_module.storages}
+        self._object_classes = {o.symbol.symbol_id: o.class_name for o in ir_module.objects}
+        self._symbol_values: dict[object, frozenset[int]] = {}
+        self._list_values: dict[object, frozenset[int]] = {}
+        self._servo_attach_sites: list[SourceSpan] = []
+        self._servo_attached_objects: set[object] = set()
+        self._pwm_timer1_sites: list[SourceSpan] = []
+        self._pwm_timer2_sites: list[SourceSpan] = []
+        self._tone_sites: list[SourceSpan] = []
+        self._serial_sites: list[SourceSpan] = []
+        self._serial_pin_sites: list[SourceSpan] = []
+        self._i2c_sites: list[SourceSpan] = []
+        self._i2c_pin_sites: list[SourceSpan] = []
+        self._explicit_serial_bauds: set[int] = set()
+        self._function_return_values: dict[object, frozenset[int]] = {}
+        self._object_arg_values: dict[object, tuple[int | None, ...]] = {}
+        self._lcd_begin_needs_wire = False
+        self._prepare_static_values()
+        self._prepare_function_return_values()
+
+    def analyze(self) -> TargetPlan:
+        self._analyze_object_declarations()
+        self._collect_dependencies_from_all_ir()
+        self._validate_known_constraints_in_all_functions()
+
+        serial_auto, serial_baud = self._analyze_serial_policy()
+
+        env = dict(self._symbol_values)
+        life = _LifeState(serial_begun=serial_auto)
+        if serial_auto:
+            self._lifecycle_facts.add("Serial begun automatically at 9600")
+        life, env = self._walk_sequence(self.ir.setup, life, env, call_stack=())
+        # setup lifecycle facts dominate each Arduino loop invocation.
+        self._walk_sequence(self.ir.main_loop, life.copy(), dict(env), call_stack=())
+
+        self._emit_resource_conflict_warnings()
+        self._validate_servo_capacity()
+        static_sram = self._estimate_static_sram()
+        self._validate_memory(static_sram)
+
+        hooks: list[str] = []
+        if serial_auto:
+            hooks.append("Serial.begin(9600);")
+        if self._lcd_begin_needs_wire:
+            hooks.append("Wire.begin();")
+            self._lifecycle_facts.add("Wire begun automatically for LiquidCrystal_I2C.begin()")
+        setup_hooks = tuple(hooks)
+        return TargetPlan(
+            board=self.board,
+            ir_module=self.ir,
+            includes=tuple(["Arduino.h", *sorted(self._includes - {"Arduino.h"})]),
+            dependency_ids=tuple(sorted(self._dependencies)),
+            setup_hooks=setup_hooks,
+            resolved_serial_baud=serial_baud,
+            diagnostics=tuple(self._diagnostics),
+            static_sram_estimate=static_sram,
+            resources=frozenset(self._resources),
+            lifecycle_facts=tuple(sorted(self._lifecycle_facts)),
+            object_arg_values=tuple(self._object_arg_values.items()),
+            serial_output=getattr(self, "_serial_output", False),
+        )
+
+    # ---------- Serial policy / initialization ----------
+    def _analyze_serial_policy(self) -> tuple[bool, int | None]:
+        """Resolve the single V1 Serial initialization policy.
+
+        Python ``print()`` owns an automatic 9600-baud setup hook unless the
+        student supplied one valid, direct setup-time ``Serial.begin``.  Any
+        explicit begin outside top-level setup is rejected so target lifecycle
+        analysis can reason about one stable configuration.
+        """
+
+        begin_calls: list[tuple[IRCall, str, bool]] = []
+        has_python_print = False
+        explicit_serial_io: list[IRCall] = []
+
+        def visit_expr(expr: IRExpr, context: str, top_level: bool) -> None:
+            if isinstance(expr, IRCall):
+                if (
+                    expr.kind == IRCallKind.SINGLETON_METHOD
+                    and expr.owner_name == "Serial"
+                ):
+                    if expr.method_name == "begin":
+                        begin_calls.append((expr, context, top_level))
+                    else:
+                        explicit_serial_io.append(expr)
+                for arg in expr.args:
+                    visit_expr(arg, context, False)
+            elif isinstance(expr, IRUnary):
+                visit_expr(expr.operand, context, False)
+            elif isinstance(expr, IRBinary):
+                visit_expr(expr.left, context, False); visit_expr(expr.right, context, False)
+            elif isinstance(expr, IRCompareChain):
+                for item in expr.operands: visit_expr(item, context, False)
+            elif isinstance(expr, IRBool):
+                for item in expr.values: visit_expr(item, context, False)
+            elif isinstance(expr, IRConditional):
+                visit_expr(expr.condition, context, False)
+                visit_expr(expr.when_true, context, False)
+                visit_expr(expr.when_false, context, False)
+            elif isinstance(expr, IRIndex):
+                visit_expr(expr.collection, context, False); visit_expr(expr.index, context, False)
+            elif isinstance(expr, IRListLiteral):
+                for item in expr.elements: visit_expr(item, context, False)
+            elif isinstance(expr, IRFormatString):
+                for part in expr.parts:
+                    if not isinstance(part, str): visit_expr(part.value, context, False)
+
+        def visit_stmts(stmts: tuple[IRStmt, ...], context: str, direct: bool) -> None:
+            nonlocal has_python_print
+            for stmt in stmts:
+                if isinstance(stmt, IRPrint):
+                    has_python_print = True
+                    for value in stmt.values: visit_expr(value, context, False)
+                elif isinstance(stmt, IRExprStmt):
+                    visit_expr(stmt.expression, context, direct)
+                elif isinstance(stmt, IRStore):
+                    visit_expr(stmt.value, context, False)
+                elif isinstance(stmt, IRIndexStore):
+                    visit_expr(stmt.index, context, False); visit_expr(stmt.value, context, False)
+                elif isinstance(stmt, IRAugStore):
+                    visit_expr(stmt.value, context, False)
+                elif isinstance(stmt, IRIf):
+                    visit_expr(stmt.condition, context, False)
+                    visit_stmts(stmt.body, context, False); visit_stmts(stmt.otherwise, context, False)
+                elif isinstance(stmt, IRWhile):
+                    visit_expr(stmt.condition, context, False); visit_stmts(stmt.body, context, False)
+                elif isinstance(stmt, IRRangeLoop):
+                    visit_expr(stmt.start, context, False); visit_expr(stmt.stop, context, False); visit_expr(stmt.step, context, False)
+                    visit_stmts(stmt.body, context, False)
+                elif isinstance(stmt, IRFixedListLoop):
+                    if stmt.index_start is not None: visit_expr(stmt.index_start, context, False)
+                    visit_stmts(stmt.body, context, False)
+                elif isinstance(stmt, IRReturn) and stmt.value is not None:
+                    visit_expr(stmt.value, context, False)
+
+        visit_stmts(self.ir.setup, "setup", True)
+        visit_stmts(self.ir.main_loop, "main loop", True)
+        for fn in self.ir.functions:
+            visit_stmts(fn.body, f"function '{fn.symbol.source_name}'", True)
+
+        # PC-side monitor metadata: does the program ever write to USB Serial?
+        self._serial_output = bool(has_python_print) or any(
+            c.method_name in {"print", "println", "write"} for c in explicit_serial_io
+        )
+
+        if len(begin_calls) > 1:
+            call = begin_calls[1][0]
+            self._hardware_error(
+                "Barmaja PyArduino V1 allows only one explicit Serial.begin(...) call.",
+                call.span,
+                "Keep one setup-time Serial.begin(baud) call and remove the others.",
+            )
+
+        explicit_baud: int | None = None
+        if begin_calls:
+            call, context, is_top_level = begin_calls[0]
+            if context != "setup" or not is_top_level:
+                self._hardware_error(
+                    "Serial.begin(...) must be a direct top-level setup statement in Barmaja PyArduino V1.",
+                    call.span,
+                    "Move Serial.begin(baud) before the main while True loop and outside functions/conditions.",
+                )
+            if len(call.args) != 1:
+                self._hardware_error("Serial.begin(...) requires exactly one baud value.", call.span)
+            explicit_baud = self._single_int(call.args[0], dict(self._symbol_values))
+            if explicit_baud is None or explicit_baud <= 0:
+                self._hardware_error(
+                    "Serial.begin(...) baud must be a positive compile-time integer.",
+                    call.span,
+                    "Use a fixed value such as Serial.begin(9600) or Serial.begin(115200).",
+                )
+
+        if explicit_baud is not None:
+            self._explicit_serial_bauds.add(explicit_baud)
+            return False, explicit_baud
+        if has_python_print:
+            return True, 9600
+        if explicit_serial_io:
+            first = explicit_serial_io[0]
+            self._hardware_error(
+                f"Serial.{first.method_name}() requires Serial.begin(baud) in setup when Python print() is not used.",
+                first.span,
+                "Add Serial.begin(9600) or another fixed positive baud before the main loop.",
+            )
+        return False, None
+
+    # ---------- declarations / dependency selection ----------
+    def _prepare_static_values(self) -> None:
+        for decl in self.ir.storages:
+            if decl.initializer is None:
+                continue
+            values = self._value_set(decl.initializer, {})
+            if values is not None:
+                if decl.symbol.type.kind == TypeKind.FIXED_LIST:
+                    self._list_values[decl.symbol.symbol_id] = values
+                elif len(values) <= 64:
+                    self._symbol_values[decl.symbol.symbol_id] = values
+
+        # Some storage declarations intentionally omit initializers in IR because
+        # initialization is represented in the executable setup/module stream.
+        # Recover immutable fixed-list/tuple constant facts from the already
+        # resolved source tree so pin-set analysis can prove safe loop patterns.
+        resolved = self.numeric.typed.resolved
+        unknown_lists: set = set()
+        for node in ast.walk(resolved.frontend.tree):
+            if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+                continue
+            target = node.targets[0]
+            if isinstance(target, ast.Name) and isinstance(node.value, ast.List):
+                vals = self._ast_int_values(node.value.elts)
+                try:
+                    sym = resolved.symbol_for_name(target)
+                except KeyError:
+                    continue
+                sid = sym.symbol_id
+                # A list may be rebound to several literals: its facts are the UNION of
+                # all of them, and any non-constant literal makes the list unknown.
+                if vals is None or sid in unknown_lists:
+                    unknown_lists.add(sid)
+                    self._list_values.pop(sid, None)
+                    continue
+                merged = self._list_values.get(sid, frozenset()) | vals
+                if len(merged) > 64:
+                    unknown_lists.add(sid)
+                    self._list_values.pop(sid, None)
+                else:
+                    self._list_values[sid] = merged
+            elif isinstance(target, (ast.Tuple, ast.List)) and isinstance(node.value, (ast.Tuple, ast.List)):
+                for t, v in zip(target.elts, node.value.elts):
+                    if not isinstance(t, ast.Name):
+                        continue
+                    value = self._ast_single_int(v)
+                    if value is None:
+                        continue
+                    try:
+                        sym = resolved.symbol_for_name(t)
+                    except KeyError:
+                        continue
+                    self._symbol_values[sym.symbol_id] = frozenset({value})
+
+        self._merge_list_element_stores()
+
+    def _merge_list_element_stores(self) -> None:
+        """Pin facts for a fixed list must include every value stored into it anywhere.
+
+        An element store whose value is not statically known makes the list's
+        pin set unknown, so later pin checks cannot trust the initializer alone.
+        """
+        stores: list[IRIndexStore] = []
+        def visit(stmts) -> None:
+            for stmt in stmts:
+                if isinstance(stmt, IRIndexStore):
+                    stores.append(stmt)
+                for child_name in ("body", "otherwise"):
+                    child = getattr(stmt, child_name, None)
+                    if isinstance(child, tuple):
+                        visit(child)
+        visit(self.ir.setup); visit(self.ir.main_loop)
+        for fn in self.ir.functions:
+            visit(fn.body)
+        for stmt in stores:
+            sid = stmt.collection.symbol_id
+            if sid not in self._list_values:
+                continue
+            values = self._value_set(stmt.value, {})
+            if values is None:
+                del self._list_values[sid]
+                continue
+            merged = self._list_values[sid] | values
+            if len(merged) > 64:
+                del self._list_values[sid]
+            else:
+                self._list_values[sid] = merged
+
+    @staticmethod
+    def _ast_single_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
+        if isinstance(node, ast.Name) and node.id in CONSTANT_VALUES:
+            return CONSTANT_VALUES[node.id]
+        return None
+
+    @classmethod
+    def _ast_int_values(cls, nodes: list[ast.AST]) -> frozenset[int] | None:
+        values: set[int] = set()
+        for node in nodes:
+            value = cls._ast_single_int(node)
+            if value is None:
+                return None
+            values.add(value)
+        return frozenset(values)
+
+
+    def _prepare_function_return_values(self) -> None:
+        # Small fixed-point summary used only to prove finite hardware-pin sets.
+        # Functions whose return depends on unknown parameters remain unknown.
+        for _ in range(8):
+            changed = False
+            for fn in self.ir.functions:
+                values: set[int] = set()
+                valid = True
+                found = False
+                for stmt in fn.body:
+                    if isinstance(stmt, IRReturn) and stmt.value is not None:
+                        found = True
+                        got = self._value_set(stmt.value, {})
+                        if got is None:
+                            valid = False
+                            break
+                        values.update(got)
+                    elif isinstance(stmt, IRIf):
+                        for branch_stmt in (*stmt.body, *stmt.otherwise):
+                            if isinstance(branch_stmt, IRReturn) and branch_stmt.value is not None:
+                                found = True
+                                got = self._value_set(branch_stmt.value, {})
+                                if got is None:
+                                    valid = False
+                                    break
+                                values.update(got)
+                        if not valid:
+                            break
+                if valid and found and len(values) <= 64:
+                    frozen = frozenset(values)
+                    if self._function_return_values.get(fn.symbol.symbol_id) != frozen:
+                        self._function_return_values[fn.symbol.symbol_id] = frozen
+                        changed = True
+            if not changed:
+                break
+
+    def _analyze_object_declarations(self) -> None:
+        software_serial = [o for o in self.ir.objects if o.class_name in {"BluetoothSerial", "GPSModule", "WiFiESPAT"}
+                           or "softserial" in HARDWARE_CLASSES[o.class_name].resources]
+        if len(software_serial) > 1:
+            self._hardware_error("Uno SoftwareSerial supports only one active receiver; use only one BluetoothSerial/GPSModule/WiFiESPAT device per sketch.", software_serial[1].span)
+        for obj in self.ir.objects:
+            spec = HARDWARE_CLASSES[obj.class_name]
+            self._select_dependencies(spec.includes, spec.dependency_ids, spec.resources)
+            resolved: list[int | None] = []
+            for arg in obj.args:
+                value = self._single_int(arg, self._symbol_values)
+                if value is None and not self._is_static_ctor_arg(arg):
+                    self._hardware_error(
+                        f"{obj.class_name}() arguments must be compile-time values (numbers or constants).",
+                        obj.span,
+                        "Use a number or a variable that is assigned only once, e.g. trig = 7.",
+                    )
+                resolved.append(value)
+            self._object_arg_values[obj.symbol.symbol_id] = tuple(resolved)
+            if obj.class_name in _packs.LOADED:
+                self._analyze_pack_object(obj, resolved, _packs.LOADED[obj.class_name])
+                continue
+            if obj.class_name == "DHT":
+                self._require_compile_time_pin(obj.args[0], self.board.digital_capable_pins, "DHT pin", obj.span)
+                self._record_shared_pin_use(frozenset(v for v in resolved[:1] if v is not None), obj.span)
+            elif obj.class_name == "Ultrasonic":
+                self._require_compile_time_pin(obj.args[0], self.board.digital_capable_pins, "Ultrasonic trigger pin", obj.span)
+                self._require_compile_time_pin(obj.args[1], self.board.digital_capable_pins, "Ultrasonic echo pin", obj.span)
+                self._record_shared_pin_use(frozenset(v for v in resolved[:2] if v is not None), obj.span)
+            elif obj.class_name in {"BluetoothSerial", "GPSModule", "WiFiESPAT"}:
+                pins = resolved
+                if any(p is None or p not in self.board.digital_capable_pins for p in pins) or len(set(pins)) != 2:
+                    self._hardware_error(f"{obj.class_name} requires two distinct Uno digital pins: RX and TX.", obj.span)
+                if any(p in (0, 1) for p in pins if p is not None):
+                    self._hardware_error(f"{obj.class_name} should not use Uno USB serial pins D0/D1. Use e.g. D6/D7.", obj.span)
+                self._record_shared_pin_use(frozenset(p for p in pins if p is not None), obj.span)
+            elif obj.class_name == "MPU6050Sensor":
+                self._resources.add("i2c")
+                if obj.span: self._i2c_sites.append(obj.span)
+            elif obj.class_name == "EthernetW5500":
+                cs = resolved[0]
+                if cs is None or cs not in self.board.digital_capable_pins:
+                    self._hardware_error("EthernetW5500 requires a valid SPI chip-select digital pin.", obj.span)
+                if cs in (11,12,13):
+                    self._hardware_error("EthernetW5500 CS cannot be D11/D12/D13; these are SPI data/clock pins.", obj.span)
+                for byte in resolved[1:]:
+                    if byte is None or not 0 <= byte <= 255:
+                        self._hardware_error("EthernetW5500 MAC bytes must be compile-time values 0..255.", obj.span)
+                if resolved[1] is not None and (resolved[1] & 1):
+                    self._hardware_error("EthernetW5500 MAC must be unicast (first byte least significant bit = 0).", obj.span)
+                self._resources.add("spi")
+                if cs is not None: self._record_shared_pin_use(frozenset({cs}), obj.span)
+            elif obj.class_name == "RFID":
+                ss, rst = resolved
+                if ss is not None and ss != 10:
+                    self._hardware_error("RFID uses SPI chip select D10 in the standard BARMAJA Uno wiring.", obj.span, "Use RFID(10, 9) unless a verified advanced circuit explicitly changes SS.")
+                for pin in (ss,rst):
+                    if pin is None or pin not in self.board.digital_capable_pins:
+                        self._hardware_error("RFID pins must be real Arduino Uno digital pins.", obj.span)
+                self._record_shared_pin_use(frozenset(p for p in (ss,rst) if p is not None), obj.span)
+                self._resources.add("spi")
+            elif obj.class_name == "IRRemote":
+                pin = resolved[0]
+                if pin is None or pin not in self.board.digital_capable_pins:
+                    self._hardware_error("IRRemote receiver pin must be a real Arduino Uno digital pin.", obj.span)
+                if pin is not None: self._record_shared_pin_use(frozenset({pin}), obj.span)
+            elif obj.class_name == "Keypad4x4":
+                pins = resolved
+                if any(p is None or p not in self.board.digital_capable_pins for p in pins) or len(set(pins)) != 8:
+                    self._hardware_error("Keypad4x4 requires eight distinct Arduino Uno digital-capable pins.", obj.span)
+                self._record_shared_pin_use(frozenset(p for p in pins if p is not None), obj.span)
+            elif obj.class_name == "StepperMotor":
+                pins = resolved
+                if any(p is None or p not in self.board.digital_capable_pins for p in pins) or len(set(pins)) != 4:
+                    self._hardware_error("StepperMotor requires four distinct Arduino Uno digital-capable pins.", obj.span)
+                self._record_shared_pin_use(frozenset(p for p in pins if p is not None), obj.span)
+            elif obj.class_name in {"LEDMatrixMAX7219", "FourDigitTM1637", "OneWireBus"}:
+                pins = resolved
+                if any(p is None or p not in self.board.digital_capable_pins for p in pins) or len(set(pins)) != len(pins):
+                    self._hardware_error(f"{obj.class_name} requires distinct compile-time Uno digital pins.", obj.span)
+                self._record_shared_pin_use(frozenset(p for p in pins if p is not None), obj.span)
+            elif obj.class_name == "LiquidCrystal_I2C":
+                self._resources.add("i2c")
+                if obj.span:
+                    self._i2c_sites.append(obj.span)
+                address = self._single_int(obj.args[0], {})
+                cols = self._single_int(obj.args[1], {})
+                rows = self._single_int(obj.args[2], {})
+                if address is None or not (0 <= address <= 0x7F):
+                    self._hardware_error("LiquidCrystal_I2C address must be a compile-time value in 0..127.", obj.span)
+                if cols is None or rows is None or not (1 <= cols <= 255) or not (1 <= rows <= 255):
+                    self._hardware_error("LiquidCrystal_I2C columns and rows must be compile-time values in 1..255.", obj.span)
+
+    def _rebinds_list(self, body, symbol_id, visiting: set) -> bool:
+        """True if `body` (or a user function it calls) stores a whole new list to symbol_id."""
+        from dataclasses import fields, is_dataclass
+
+        functions = {fn.symbol.symbol_id: fn for fn in self.ir.functions}
+
+        def walk(value) -> bool:
+            if isinstance(value, IRStore) and value.target.symbol_id == symbol_id:
+                return True
+            if isinstance(value, IRCall) and value.kind == IRCallKind.USER_FUNCTION and value.function_symbol is not None:
+                fid = value.function_symbol.symbol_id
+                if fid not in visiting and fid in functions:
+                    visiting.add(fid)
+                    if walk(functions[fid].body):
+                        return True
+            if is_dataclass(value) and not isinstance(value, type):
+                return any(walk(getattr(value, f.name)) for f in fields(value))
+            if isinstance(value, (tuple, list)):
+                return any(walk(item) for item in value)
+            return False
+
+        return walk(body)
+
+    def _record_shared_pin_use(self, values, span: SourceSpan | None) -> None:
+        """Device pins on UART 0/1 or I2C A4/A5 feed the same conflict warnings as digital I/O."""
+        if not values or span is None:
+            return
+        if set(values) & set(self.board.uart_pins):
+            self._serial_pin_sites.append(span)
+        if set(values) & set(self.board.i2c_pins):
+            self._i2c_pin_sites.append(span)
+
+    @staticmethod
+    def _is_static_ctor_arg(arg: IRExpr) -> bool:
+        from .symbols import SymbolKind
+        if isinstance(arg, IRConstant):
+            return True
+        return isinstance(arg, IRLoad) and arg.symbol.kind in {SymbolKind.API, SymbolKind.BUILTIN}
+
+    def _select_dependencies(self, includes: Iterable[str], dependency_ids: Iterable[str], resources: Iterable[str]) -> None:
+        self._includes.update(includes)
+        self._resources.update(resources)
+        pending = list(dependency_ids)
+        while pending:
+            dep_id = pending.pop()
+            if dep_id in self._dependencies:
+                continue
+            self._dependencies.add(dep_id)
+            dep = DEPENDENCIES[dep_id]
+            if dep.include:
+                self._includes.add(dep.include)
+            pending.extend(dep.transitive)
+
+    def _collect_dependencies_from_all_ir(self) -> None:
+        """Collect headers/dependencies from emitted IR, including unused functions.
+
+        Backend emission includes function bodies even when they are never called,
+        so singleton/library references there still require their headers.
+        """
+        def visit_expr(expr: IRExpr) -> None:
+            if isinstance(expr, IRCall):
+                if expr.kind == IRCallKind.API_FUNCTION:
+                    spec = CORE_FUNCTIONS.get(expr.name)
+                    if spec:
+                        self._select_dependencies((spec.include,) if spec.include else (), (spec.dependency_id,) if spec.dependency_id else (), spec.resources)
+                elif expr.kind == IRCallKind.SINGLETON_METHOD and expr.owner_name in SINGLETONS:
+                    spec = SINGLETONS[expr.owner_name]
+                    self._select_dependencies(spec.includes, spec.dependency_ids, spec.resources)
+                elif expr.kind == IRCallKind.OBJECT_METHOD and expr.owner_symbol is not None:
+                    cls = self._object_classes.get(expr.owner_symbol.symbol_id) or expr.owner_symbol.type.hardware_class
+                    if cls in HARDWARE_CLASSES:
+                        spec = HARDWARE_CLASSES[cls]
+                        self._select_dependencies(spec.includes, spec.dependency_ids, spec.resources)
+                for a in expr.args: visit_expr(a)
+            elif isinstance(expr, IRListLiteral):
+                for x in expr.elements: visit_expr(x)
+            elif isinstance(expr, IRIndex):
+                visit_expr(expr.collection); visit_expr(expr.index)
+            elif isinstance(expr, IRUnary): visit_expr(expr.operand)
+            elif isinstance(expr, IRBinary): visit_expr(expr.left); visit_expr(expr.right)
+            elif isinstance(expr, IRCompareChain):
+                for x in expr.operands: visit_expr(x)
+            elif isinstance(expr, IRBool):
+                for x in expr.values: visit_expr(x)
+            elif isinstance(expr, IRConditional):
+                visit_expr(expr.condition); visit_expr(expr.when_true); visit_expr(expr.when_false)
+            elif isinstance(expr, IRFormatString):
+                for part in expr.parts:
+                    if not isinstance(part, str): visit_expr(part.value)
+
+        def visit_stmts(stmts: tuple[IRStmt, ...]) -> None:
+            for stmt in stmts:
+                if isinstance(stmt, IRExprStmt): visit_expr(stmt.expression)
+                elif isinstance(stmt, IRPrint):
+                    self._resources.add("uart")
+                    for x in stmt.values: visit_expr(x)
+                elif isinstance(stmt, IRStore): visit_expr(stmt.value)
+                elif isinstance(stmt, IRIndexStore): visit_expr(stmt.index); visit_expr(stmt.value)
+                elif isinstance(stmt, IRAugStore): visit_expr(stmt.value)
+                elif isinstance(stmt, IRIf): visit_expr(stmt.condition); visit_stmts(stmt.body); visit_stmts(stmt.otherwise)
+                elif isinstance(stmt, IRWhile): visit_expr(stmt.condition); visit_stmts(stmt.body)
+                elif isinstance(stmt, IRRangeLoop): visit_expr(stmt.start); visit_expr(stmt.stop); visit_expr(stmt.step); visit_stmts(stmt.body)
+                elif isinstance(stmt, IRFixedListLoop):
+                    if stmt.index_start is not None: visit_expr(stmt.index_start)
+                    visit_stmts(stmt.body)
+                elif isinstance(stmt, IRReturn) and stmt.value is not None: visit_expr(stmt.value)
+        visit_stmts(self.ir.setup)
+        visit_stmts(self.ir.main_loop)
+        for fn in self.ir.functions:
+            visit_stmts(fn.body)
+
+    def _validate_known_constraints_in_all_functions(self) -> None:
+        """Catch impossible literal pin use even in currently unreachable functions.
+
+        Unknown parameters are intentionally left for call-site proof so useful
+        helpers like ``def set_led(pin): ...`` remain supported.
+        """
+        def visit_expr(expr: IRExpr) -> None:
+            if isinstance(expr, IRCall):
+                if expr.kind == IRCallKind.API_FUNCTION and expr.args:
+                    values = self._value_set(expr.args[0], {})
+                    if values is not None:
+                        if expr.name in {"pinMode", "digitalWrite", "digitalRead", "tone", "noTone"}:
+                            bad = set(values) - set(self.board.digital_capable_pins)
+                            if bad: self._hardware_error(f"{expr.name}() contains invalid {self.board.name} pin value(s): {', '.join(map(str, sorted(bad)))}.", expr.span)
+                        elif expr.name == "analogRead":
+                            is_alias = isinstance(expr.args[0], IRLoad) and expr.args[0].symbol.source_name in self.board.analog_aliases
+                            if not is_alias and not set(values).issubset(set(self.board.analog_channels)):
+                                self._hardware_error(f"analogRead() pin must be A0..A5 or compatibility channel 0..5 on {self.board.name}.", expr.span)
+                        elif expr.name == "analogWrite" and not set(values).issubset(set(self.board.pwm_pins)):
+                            self._hardware_error(f"analogWrite() uses a non-PWM pin on {self.board.name}.", expr.span)
+                elif expr.kind == IRCallKind.OBJECT_METHOD and expr.method_name == "attach" and expr.owner_symbol and expr.owner_symbol.type.hardware_class == "Servo":
+                    values = self._value_set(expr.args[0], {}) if expr.args else None
+                    if values is not None and not set(values).issubset(set(self.board.digital_capable_pins)):
+                        self._hardware_error(f"Servo attach pin is invalid on {self.board.name}.", expr.span)
+                for a in expr.args: visit_expr(a)
+            elif isinstance(expr, IRUnary): visit_expr(expr.operand)
+            elif isinstance(expr, IRBinary): visit_expr(expr.left); visit_expr(expr.right)
+            elif isinstance(expr, IRCompareChain):
+                for x in expr.operands: visit_expr(x)
+            elif isinstance(expr, IRBool):
+                for x in expr.values: visit_expr(x)
+            elif isinstance(expr, IRConditional): visit_expr(expr.condition); visit_expr(expr.when_true); visit_expr(expr.when_false)
+            elif isinstance(expr, IRIndex): visit_expr(expr.collection); visit_expr(expr.index)
+            elif isinstance(expr, IRListLiteral):
+                for x in expr.elements: visit_expr(x)
+            elif isinstance(expr, IRFormatString):
+                for part in expr.parts:
+                    if not isinstance(part, str): visit_expr(part.value)
+        def visit_stmts(stmts: tuple[IRStmt, ...]) -> None:
+            for stmt in stmts:
+                if isinstance(stmt, IRExprStmt): visit_expr(stmt.expression)
+                elif isinstance(stmt, IRPrint):
+                    for x in stmt.values: visit_expr(x)
+                elif isinstance(stmt, IRStore): visit_expr(stmt.value)
+                elif isinstance(stmt, IRIndexStore): visit_expr(stmt.index); visit_expr(stmt.value)
+                elif isinstance(stmt, IRAugStore): visit_expr(stmt.value)
+                elif isinstance(stmt, IRIf): visit_expr(stmt.condition); visit_stmts(stmt.body); visit_stmts(stmt.otherwise)
+                elif isinstance(stmt, IRWhile): visit_expr(stmt.condition); visit_stmts(stmt.body)
+                elif isinstance(stmt, (IRRangeLoop, IRFixedListLoop)): visit_stmts(stmt.body)
+                elif isinstance(stmt, IRReturn) and stmt.value is not None: visit_expr(stmt.value)
+        for fn in self.ir.functions:
+            visit_stmts(fn.body)
+
+    # ---------- sequence/lifecycle analysis ----------
+    def _walk_sequence(self, statements: tuple[IRStmt, ...], life: _LifeState, env: dict, call_stack: tuple) -> tuple[_LifeState, dict]:
+        for stmt in statements:
+            if isinstance(stmt, IRStore):
+                self._walk_expr(stmt.value, life, env, call_stack)
+                values = self._value_set(stmt.value, env)
+                if stmt.target.type.kind == TypeKind.TIME_U32 and stmt.value.type.kind == TypeKind.INT and values and max(values) < 0:
+                    self._hardware_error(
+                        f"'{stmt.target.source_name}' holds a millis() time, so it cannot be negative.",
+                        stmt.span,
+                        "Start timer variables at 0 or at millis().",
+                    )
+                if values is not None and len(values) <= 64:
+                    env[stmt.target.symbol_id] = values
+                else:
+                    env.pop(stmt.target.symbol_id, None)
+            elif isinstance(stmt, IRIndexStore):
+                self._walk_expr(stmt.index, life, env, call_stack)
+                self._walk_expr(stmt.value, life, env, call_stack)
+            elif isinstance(stmt, IRAugStore):
+                self._walk_expr(stmt.value, life, env, call_stack)
+                env.pop(stmt.target.symbol_id, None)
+            elif isinstance(stmt, IRExprStmt):
+                self._walk_expr(stmt.expression, life, env, call_stack)
+            elif isinstance(stmt, IRPrint):
+                self._resources.add("uart")
+                if stmt.span:
+                    self._serial_sites.append(stmt.span)
+                if not life.serial_begun:
+                    self._hardware_error(
+                        "Python print() executes before Serial is initialized.",
+                        stmt.span,
+                        "Move the explicit Serial.begin(baud) before this output, or remove it and let Python print() use automatic 9600 baud.",
+                    )
+                for expr in stmt.values:
+                    self._walk_expr(expr, life, env, call_stack)
+            elif isinstance(stmt, IRIf):
+                self._walk_expr(stmt.condition, life, env, call_stack)
+                left_life, left_env = self._walk_sequence(stmt.body, life.copy(), dict(env), call_stack)
+                right_life, right_env = self._walk_sequence(stmt.otherwise, life.copy(), dict(env), call_stack)
+                life = _LifeState.intersect(left_life, right_life)
+                env = self._intersect_env(left_env, right_env)
+            elif isinstance(stmt, IRWhile):
+                self._walk_expr(stmt.condition, life, env, call_stack)
+                self._walk_sequence(stmt.body, life.copy(), dict(env), call_stack)
+            elif isinstance(stmt, IRRangeLoop):
+                self._walk_expr(stmt.start, life, env, call_stack)
+                self._walk_expr(stmt.stop, life, env, call_stack)
+                self._walk_expr(stmt.step, life, env, call_stack)
+                # A step that is a compile-time constant expression equal to zero
+                # (e.g. STEP = 0 or N - N) is a program error in Python (ValueError);
+                # report it before code generation instead of relying on the runtime trap.
+                if self._single_int(stmt.step, {}) == 0:
+                    where = stmt.step.span or stmt.span
+                    raise CompileError(
+                        "range() step cannot be zero.",
+                        where.line if where else None,
+                        (where.column + 1) if where else None,
+                        end_line=where.end_line if where else None,
+                        end_column=where.end_column if where else None,
+                    )
+                loop_env = dict(env)
+                values = self._range_values(stmt.start, stmt.stop, stmt.step, env)
+                if values is not None:
+                    loop_env[stmt.target.symbol_id] = values
+                self._walk_sequence(stmt.body, life.copy(), loop_env, call_stack)
+            elif isinstance(stmt, IRFixedListLoop):
+                if self._rebinds_list(stmt.body, stmt.collection.symbol_id, set()):
+                    # Python keeps iterating the ORIGINAL list object when the name is
+                    # rebound to a new list; a fixed Uno array is overwritten in place.
+                    where = stmt.span
+                    raise UnsupportedFeatureError(
+                        f"Do not assign a new list to '{stmt.collection.source_name}' while a for-loop is iterating over it "
+                        "(Python would keep looping over the old list). Change single elements, for example values[i] = x, "
+                        "or store the new list in another variable.",
+                        line=where.line if where else None,
+                        column=(where.column + 1) if where else None,
+                    )
+                loop_env = dict(env)
+                values = self._list_values.get(stmt.collection.symbol_id)
+                if values:
+                    loop_env[stmt.value_target.symbol_id] = values
+                if stmt.index_start is not None:
+                    self._walk_expr(stmt.index_start, life, env, call_stack)
+                self._walk_sequence(stmt.body, life.copy(), loop_env, call_stack)
+            elif isinstance(stmt, IRReturn):
+                if stmt.value is not None:
+                    self._walk_expr(stmt.value, life, env, call_stack)
+            # break/continue carry no target facts.
+        return life, env
+
+    def _walk_expr(self, expr: IRExpr, life: _LifeState, env: dict, call_stack: tuple) -> None:
+        if isinstance(expr, (IRConstant, IRLoad)):
+            return
+        if isinstance(expr, IRListLiteral):
+            for x in expr.elements: self._walk_expr(x, life, env, call_stack)
+            return
+        if isinstance(expr, IRIndex):
+            self._walk_expr(expr.collection, life, env, call_stack); self._walk_expr(expr.index, life, env, call_stack); return
+        if isinstance(expr, IRUnary):
+            self._walk_expr(expr.operand, life, env, call_stack); return
+        if isinstance(expr, IRBinary):
+            self._walk_expr(expr.left, life, env, call_stack); self._walk_expr(expr.right, life, env, call_stack); return
+        if isinstance(expr, IRCompareChain):
+            for x in expr.operands: self._walk_expr(x, life, env, call_stack)
+            return
+        if isinstance(expr, IRBool):
+            for x in expr.values: self._walk_expr(x, life, env, call_stack)
+            return
+        if isinstance(expr, IRConditional):
+            self._walk_expr(expr.condition, life, env, call_stack)
+            self._walk_expr(expr.when_true, life.copy(), dict(env), call_stack)
+            self._walk_expr(expr.when_false, life.copy(), dict(env), call_stack)
+            return
+        if isinstance(expr, IRFormatString):
+            for part in expr.parts:
+                if not isinstance(part, str): self._walk_expr(part.value, life, env, call_stack)
+            return
+        if isinstance(expr, IRCall):
+            for arg in expr.args:
+                self._walk_expr(arg, life, env, call_stack)
+            self._handle_call(expr, life, env, call_stack)
+            return
+        raise InternalCompilerError(f"Target analysis has no expression path for {type(expr).__name__}.")
+
+    def _handle_call(self, call: IRCall, life: _LifeState, env: dict, call_stack: tuple) -> None:
+        if call.kind == IRCallKind.USER_FUNCTION:
+            if call.function_symbol is None:
+                raise InternalCompilerError("User call reached target analysis without a function symbol.")
+            sid = call.function_symbol.symbol_id
+            if sid in call_stack:
+                return  # recursion is rejected earlier; defensive only.
+            fn = self._functions.get(sid)
+            if fn is None:
+                raise InternalCompilerError("User call reached target analysis without function IR.")
+            fn_env = dict(env)
+            for param, arg in zip(fn.parameters, call.args):
+                values = self._value_set(arg, env)
+                if values is not None and len(values) <= 64:
+                    fn_env[param.symbol_id] = values
+            self._walk_sequence(fn.body, life, fn_env, call_stack + (sid,))
+            return
+
+        if call.kind == IRCallKind.API_FUNCTION:
+            spec = CORE_FUNCTIONS.get(call.name)
+            if spec:
+                self._select_dependencies((spec.include,) if spec.include else (), (spec.dependency_id,) if spec.dependency_id else (), spec.resources)
+            self._validate_core_call(call, env)
+            return
+
+        if call.kind == IRCallKind.SINGLETON_METHOD:
+            owner = call.owner_name or ""
+            spec = SINGLETONS[owner]
+            self._select_dependencies(spec.includes, spec.dependency_ids, spec.resources)
+            method = call.method_name or ""
+            if owner == "Wire":
+                if call.span: self._i2c_sites.append(call.span)
+                if method == "begin":
+                    life.wire_begun = True; self._lifecycle_facts.add("Wire begun")
+                elif not life.wire_begun:
+                    self._hardware_error(f"Wire.{method}() requires Wire.begin() first.", call.span, "Call Wire.begin() during setup before I2C transactions.")
+                if method == "write" and call.args:
+                    self._require_values_within(call.args[0], env, 0, 255, "Wire.write() sends one byte: use a value from 0 to 255.", call.span)
+                if method in {"beginTransmission", "requestFrom"} and call.args:
+                    self._require_values_within(call.args[0], env, 0, 127, f"Wire.{method}() address must be 0..127.", call.span)
+                if method == "requestFrom" and len(call.args) >= 2:
+                    self._require_values_within(
+                        call.args[1], env, 0, 255,
+                        "Wire.requestFrom() count must be in 0..255 for the pinned AVR Wire implementation.", call.span,
+                    )
+            elif owner == "EEPROM":
+                if method in {"read", "write", "update"} and call.args:
+                    self._require_values_within(call.args[0], env, 0, 1023, "Uno EEPROM address must be 0..1023.", call.span)
+                if method in {"write", "update"} and len(call.args) > 1:
+                    self._require_values_within(call.args[1], env, 0, 255, "EEPROM stores one byte, value must be 0..255.", call.span)
+            elif owner == "SPI":
+                if method == "transfer" and call.args:
+                    self._require_values_within(call.args[0], env, 0, 255, "SPI.transfer() requires a byte 0..255.", call.span)
+            elif owner == "Serial":
+                if call.span: self._serial_sites.append(call.span)
+                self._resources.add("uart")
+                if method == "begin":
+                    baud = self._single_int(call.args[0], env) if call.args else None
+                    if baud is not None:
+                        self._explicit_serial_bauds.add(baud)
+                    life.serial_begun = True; self._lifecycle_facts.add("Serial begun explicitly")
+                elif not life.serial_begun:
+                    self._hardware_error(
+                        f"Serial.{method}() requires Serial.begin(baud) first.",
+                        call.span,
+                        "Add one setup-time Serial.begin(baud), or use Python print() when automatic 9600-baud initialization is desired.",
+                    )
+                if method in {"print", "println"} and len(call.args) == 2:
+                    self._require_values_within(
+                        call.args[1], env, 0, 255,
+                        f"Serial.{method}() format/base/digits argument must fit the pinned Arduino Print uint8 domain 0..255.",
+                        call.span,
+                    )
+            return
+
+        if call.kind == IRCallKind.OBJECT_METHOD:
+            if call.owner_symbol is None:
+                raise InternalCompilerError("Object method reached target analysis without owner symbol.")
+            sid = call.owner_symbol.symbol_id
+            cls = self._object_classes.get(sid) or call.owner_symbol.type.hardware_class
+            if cls not in HARDWARE_CLASSES:
+                raise InternalCompilerError("Unknown hardware object reached target analysis.")
+            spec = HARDWARE_CLASSES[cls]
+            self._select_dependencies(spec.includes, spec.dependency_ids, spec.resources)
+            method = call.method_name or ""
+            if cls in _packs.LOADED:
+                self._analyze_pack_method(call, env, life, sid, _packs.LOADED[cls], method)
+                return
+            if cls in {"RFID", "IRRemote", "BluetoothSerial", "MPU6050Sensor", "GPSModule", "EthernetW5500", "WiFiESPAT"}:
+                if method in ({"begin", "beginIP"} if cls == "EthernetW5500" else {"begin"}):
+                    life.modules_started.add(sid)
+                    self._lifecycle_facts.add(f"{cls} initialized")
+                elif sid not in life.modules_started:
+                    self._hardware_error(f"{cls}.{method}() requires begin() first.", call.span, f"Call the {cls.lower()} object begin() during setup.")
+            if cls in {"BluetoothSerial", "WiFiESPAT", "GPSModule"} and method == "begin" and call.args:
+                self._require_values_within(call.args[0], env, 300, 57600, f"{cls}.begin() baud must be 300..57600 for reliable Uno SoftwareSerial.", call.span)
+            if cls in {"BluetoothSerial", "EthernetW5500", "WiFiESPAT"} and method == "write" and call.args:
+                self._require_values_within(call.args[0], env, 0, 255, f"{cls}.write() requires a byte 0..255.", call.span)
+            if cls in {"EthernetW5500", "WiFiESPAT"}:
+                if method in {"beginIP", "tcpConnect"} or (cls == "EthernetW5500" and method == "connect"):
+                    for ix in range(4):
+                        self._require_values_within(call.args[ix], env, 0, 255, f"{cls} IPv4 octets must be 0..255.", call.span)
+                if method == "tcpConnect" or (cls == "EthernetW5500" and method == "connect"):
+                    self._require_values_within(call.args[4], env, 1, 65535, f"{cls} TCP port must be 1..65535.", call.span)
+            if cls == "OneWireBus" and method == "write" and call.args:
+                self._require_values_within(call.args[0], env, 0, 255, "OneWireBus.write() requires 0..255.", call.span)
+            if cls == "LEDMatrixMAX7219":
+                if method == "setPixel":
+                    for ix in (0,1): self._require_values_within(call.args[ix], env, 0, 7, "LED matrix row/column must be 0..7.", call.span)
+                if method == "setRow":
+                    self._require_values_within(call.args[0], env, 0, 7, "LED matrix row must be 0..7.", call.span)
+                    self._require_values_within(call.args[1], env, 0, 255, "LED matrix row bits must be 0..255.", call.span)
+                if method == "setBrightness": self._require_values_within(call.args[0], env, 0, 15, "MAX7219 brightness must be 0..15.", call.span)
+            if cls == "FourDigitTM1637":
+                if method == "setBrightness": self._require_values_within(call.args[0], env, 0, 7, "TM1637 brightness must be 0..7.", call.span)
+                if method == "showNumber": self._require_values_within(call.args[0], env, -999, 9999, "TM1637 number must be -999..9999.", call.span)
+            if cls == "Servo":
+                if method == "attach":
+                    self._require_compile_time_pin(call.args[0], self.board.digital_capable_pins, "Servo attach pin", call.span, env)
+                    self._record_shared_pin_use(self._value_set(call.args[0], env), call.span)
+                    life.servo_attached.add(sid)
+                    self._servo_attached_objects.add(sid)
+                    self._resources.add(self.board.servo_timer.lower())
+                    if call.span: self._servo_attach_sites.append(call.span)
+                    self._lifecycle_facts.add("Servo attached")
+                elif method == "detach":
+                    life.servo_attached.discard(sid)
+                elif method in {"write", "writeMicroseconds", "read"} and sid not in life.servo_attached:
+                    self._hardware_error(f"Servo.{method}() requires attach() first.", call.span, "Call servo.attach(pin) before using the Servo.")
+                if method == "write" and call.args:
+                    self._require_values_within(call.args[0], env, 0, 180, "Servo.write() angle must be between 0 and 180.", call.span)
+                if method == "writeMicroseconds" and call.args:
+                    self._require_values_within(call.args[0], env, 0, 3000, "Servo.writeMicroseconds() value must be a pulse width in 0..3000 microseconds.", call.span)
+                if method == "attach" and len(call.args) == 3:
+                    lo = self._single_int(call.args[1], env); hi = self._single_int(call.args[2], env)
+                    if lo is not None and hi is not None and not self._servo_attach_bounds_valid(lo, hi):
+                        self._hardware_error(
+                            "Servo.attach(pin, min, max) pulse bounds are unsafe for the pinned Servo adapter.",
+                            call.span,
+                            "Use 0 < min < max and calibration values close enough to the default 544..2400 us range to fit the library's int8 offset storage.",
+                        )
+            elif cls == "Ultrasonic":
+                if method == "setTimeout" and call.args:
+                    self._require_not_all_negative(call.args[0], env, "Ultrasonic.setTimeout() needs a non-negative timeout.", call.span)
+            elif cls == "DHT":
+                if method == "begin":
+                    life.dht_begun.add(sid); self._lifecycle_facts.add("DHT begun")
+                elif method in {"readTemperature", "readHumidity"} and sid not in life.dht_begun:
+                    self._hardware_error(f"DHT.{method}() requires begin() first.", call.span, "Call dht.begin() during setup before reading the sensor.")
+            elif cls == "LiquidCrystal_I2C":
+                self._resources.add("i2c")
+                if call.span: self._i2c_sites.append(call.span)
+                if method in {"init", "begin"}:
+                    life.lcd_inited.add(sid); self._lifecycle_facts.add("LCD initialized")
+                    if method == "init":
+                        # Pinned LiquidCrystal_I2C 1.1.4 init() calls Wire.begin()
+                        # inside init_priv(), so subsequent Wire operations are valid.
+                        life.wire_begun = True
+                        self._lifecycle_facts.add("Wire begun by LiquidCrystal_I2C.init()")
+                    else:
+                        # Pinned begin() does not call Wire.begin(); the backend adds
+                        # one setup hook for this Barmaja compatibility path.
+                        self._lcd_begin_needs_wire = True
+                        life.wire_begun = True
+                elif method in {"clear", "home", "setCursor", "print", "backlight", "noBacklight", "display", "noDisplay"} and sid not in life.lcd_inited:
+                    self._hardware_error(f"LiquidCrystal_I2C.{method}() requires init() or begin() first.", call.span, "Initialize the LCD during setup before using it.")
+                if method == "begin" and len(call.args) >= 2:
+                    self._require_values_within(
+                        call.args[0], env, 1, 255,
+                        "LiquidCrystal_I2C.begin() columns and rows must be in 1..255.", call.span,
+                    )
+                    self._require_values_within(
+                        call.args[1], env, 1, 255,
+                        "LiquidCrystal_I2C.begin() columns and rows must be in 1..255.", call.span,
+                    )
+                    if len(call.args) >= 3:
+                        values = self._value_set(call.args[2], env)
+                        if values is not None and not set(values).issubset({0x00, 0x04}):
+                            self._hardware_error(
+                                "LiquidCrystal_I2C.begin() charsize must be 0 (5x8) or 4 (5x10).",
+                                call.span,
+                            )
+                if method == "setCursor" and len(call.args) >= 2:
+                    self._require_values_within(
+                        call.args[0], env, 0, 255,
+                        "LiquidCrystal_I2C.setCursor() column must be in 0..255.", call.span,
+                    )
+                    self._require_values_within(
+                        call.args[1], env, 0, 3,
+                        "LiquidCrystal_I2C.setCursor() row must be 0, 1, 2, or 3 (HD44780 displays have at most 4 rows).", call.span,
+                    )
+                if method == "print" and call.args:
+                    self._validate_lcd_output_literals(call.args[0], call.span)
+            return
+
+    # ---------- device packs (generic rules from pack.json) ----------
+    def _analyze_pack_object(self, obj, resolved: list[int | None], pack) -> None:
+        board = self.board
+        allowed = {
+            "digital_pin": set(board.digital_capable_pins),
+            "analog_pin": set(board.analog_pins),
+            "pwm_pin": set(board.pwm_pins),
+        }
+        resolved = list(resolved) + [p.default for p in pack.constructor[len(resolved):]]
+        names = {p.name: v for p, v in zip(pack.constructor, resolved)}
+        pins: list[int] = []
+        for param, value in zip(pack.constructor, resolved):
+            if param.rule != "none":
+                if value is None or value not in allowed[param.rule]:
+                    kind = {"digital_pin": "digital", "analog_pin": "analog (A0..A5)", "pwm_pin": "PWM (~)"}[param.rule]
+                    self._hardware_error(f"{pack.class_name}() '{param.name}' must be a compile-time {kind} pin on {board.name}.", obj.span)
+                if value in pack.forbid_pins:
+                    self._hardware_error(
+                        f"{pack.class_name}() '{param.name}' cannot use pin {value} on {board.name}.", obj.span,
+                        "D0/D1 are the USB serial pins used for upload and print(); choose another pin." if value in (0, 1) else None)
+                pins.append(value)
+            if param.range is not None:
+                low = _packs.resolve_bound(param.range[0], names)
+                high = _packs.resolve_bound(param.range[1], names)
+                if value is None or (low is not None and value < low) or (high is not None and value > high):
+                    self._hardware_error(f"{pack.class_name}() '{param.name}' must be a compile-time number {low}..{high}.", obj.span)
+        if pack.distinct_pins and len(set(pins)) != len(pins):
+            self._hardware_error(f"{pack.class_name}() pins must all be different.", obj.span)
+        if "spi" in pack.resources:
+            if set(pins) & {11, 12, 13}:
+                self._hardware_error(f"{pack.class_name}() cannot use D11/D12/D13; they are the SPI bus pins.", obj.span)
+            self._record_shared_pin_use(frozenset(set(pins) | {11, 12, 13}), obj.span)
+        else:
+            self._record_shared_pin_use(frozenset(pins), obj.span)
+        if "i2c" in pack.resources and obj.span:
+            self._i2c_sites.append(obj.span)
+        for text in pack.warnings:
+            self._warn("HardwareWarning", "BJ3900", f"{pack.class_name}: {text}", obj.span)
+        if pack.status == "prototype":
+            self._warn("HardwareWarning", "BJ3901", f"{pack.class_name} is a PROTOTYPE device pack (compile-tested only, not hardware-verified).", obj.span)
+
+    def _analyze_pack_method(self, call, env: dict, life, sid, pack, method: str) -> None:
+        spec = pack.methods[method]
+        starter = next((m for m in pack.methods.values() if m.starts), None)
+        if spec.starts:
+            life.modules_started.add(sid)
+            self._lifecycle_facts.add(f"{pack.class_name} initialized")
+        elif starter is not None and spec.requires_begin and sid not in life.modules_started:
+            self._hardware_error(
+                f"{pack.class_name}.{method}() requires {starter.name}() first.", call.span,
+                f"Call {starter.name}() on the {pack.class_name} object during setup, before the main loop.")
+        if "i2c" in pack.resources and call.span:
+            self._i2c_sites.append(call.span)
+        given = list(dict(self._object_arg_values).get(sid, ()))
+        given += [p.default for p in pack.constructor[len(given):]]
+        ctor_values = dict(zip((p.name for p in pack.constructor), given))
+        for param, arg in zip(spec.params, call.args):
+            if param.rule != "none":
+                allowed = {"digital_pin": self.board.digital_capable_pins, "analog_pin": self.board.analog_pins,
+                           "pwm_pin": self.board.pwm_pins}[param.rule]
+                self._require_proven_pin(arg, allowed, f"{pack.class_name}.{method}() {param.name}", call.span, env)
+                values = self._value_set(arg, env) or ()
+                if set(values) & set(pack.forbid_pins):
+                    self._hardware_error(f"{pack.class_name}.{method}() {param.name} cannot use pin(s) {sorted(set(values) & set(pack.forbid_pins))}.", call.span)
+                self._record_shared_pin_use(frozenset(values), call.span)
+            if param.range is None or param.types != ("Int",):
+                continue
+            low = _packs.resolve_bound(param.range[0], ctor_values)
+            high = _packs.resolve_bound(param.range[1], ctor_values)
+            if low is None or high is None:
+                continue
+            self._require_values_within(arg, env, low, high,
+                                        f"{pack.class_name}.{method}() '{param.name}' must be {low}..{high}.", call.span)
+
+    def _validate_lcd_output_literals(self, expr: IRExpr, span: SourceSpan | None) -> None:
+        """Reject literal characters the pinned HD44780 adapter cannot promise."""
+
+        def check(text: str) -> None:
+            bad = [ch for ch in text if not (0x20 <= ord(ch) <= 0x7E) and ch != "°"]
+            if bad:
+                sample = bad[0]
+                self._hardware_error(
+                    f"LCD literal text contains unsupported character {sample!r}.",
+                    span,
+                    "Use printable ASCII (degree sign ° is also supported). General UTF-8/Arabic text is not supported by the V1 HD44780 adapter.",
+                )
+
+        if isinstance(expr, IRConstant) and isinstance(expr.value, str):
+            check(expr.value)
+        elif isinstance(expr, IRFormatString):
+            for part in expr.parts:
+                if isinstance(part, str):
+                    check(part)
+
+    # ---------- pin/resource validation ----------
+    def _validate_core_call(self, call: IRCall, env: dict) -> None:
+        if not call.args:
+            return
+        if call.name == "delay":
+            self._require_not_all_negative(call.args[0], env, "delay() needs a non-negative number of milliseconds.", call.span)
+        if call.name == "delayMicroseconds":
+            self._require_values_within(call.args[0], env, 0, 16383, "delayMicroseconds() accepts 0..16383 microseconds on Uno.", call.span)
+        if call.name == "tone":
+            self._require_values_within(call.args[1], env, 31, 65535, "tone() frequency must be 31..65535 Hz on Arduino Uno.", call.span)
+            if len(call.args) == 3:
+                self._require_not_all_negative(call.args[2], env, "tone() duration must be non-negative milliseconds.", call.span)
+            if call.span: self._tone_sites.append(call.span)
+        if call.name == "map":
+            a, b = self._value_set(call.args[1], env), self._value_set(call.args[2], env)
+            if a is not None and b is not None and len(a) == len(b) == 1 and next(iter(a)) == next(iter(b)):
+                self._hardware_error("map() input minimum and maximum must differ.", call.span)
+        if call.name == "constrain":
+            a, b = self._value_set(call.args[1], env), self._value_set(call.args[2], env)
+            if a is not None and b is not None and min(a) > max(b):
+                self._hardware_error("constrain() lower bound must not exceed upper bound.", call.span)
+        if call.name == "pinMode" and len(call.args) >= 2:
+            modes = self._value_set(call.args[1], env)
+            allowed = {CONSTANT_VALUES["INPUT"], CONSTANT_VALUES["OUTPUT"], CONSTANT_VALUES["INPUT_PULLUP"]}
+            if modes is not None and not set(modes).issubset(allowed):
+                self._hardware_error("pinMode() mode must be INPUT, OUTPUT, or INPUT_PULLUP.", call.span)
+        if call.name == "digitalWrite" and len(call.args) >= 2:
+            levels = self._value_set(call.args[1], env)
+            allowed = {CONSTANT_VALUES["LOW"], CONSTANT_VALUES["HIGH"]}
+            if levels is not None and not set(levels).issubset(allowed):
+                self._hardware_error("digitalWrite() value must be LOW, HIGH, False, or True.", call.span)
+        if call.name in {"pinMode", "digitalWrite", "digitalRead", "tone", "noTone"}:
+            self._require_proven_pin(call.args[0], self.board.digital_capable_pins, f"{call.name}() pin", call.span, env)
+            values = self._value_set(call.args[0], env)
+            if values and set(values) & set(self.board.uart_pins):
+                if call.span: self._serial_pin_sites.append(call.span)
+            if values and set(values) & set(self.board.i2c_pins):
+                if call.span: self._i2c_pin_sites.append(call.span)
+        elif call.name == "analogRead":
+            self._validate_analog_pin(call.args[0], call.span, env)
+            values = self._value_set(call.args[0], env)
+            # Alias A4/A5 count as independent I2C pin use; numeric channel 4/5
+            # maps to the same physical pins too.
+            if values:
+                physical = {self.board.analog_aliases.get(f"A{v}", v) if v in self.board.analog_channels else v for v in values}
+                if set(physical) & set(self.board.i2c_pins) and call.span:
+                    self._i2c_pin_sites.append(call.span)
+        elif call.name == "analogWrite":
+            values = self._value_set(call.args[0], env)
+            if values is None:
+                self._hardware_error(f"analogWrite() pin must be statically provable as a PWM pin on {self.board.name}.", call.span)
+            bad = sorted(set(values) - set(self.board.pwm_pins))
+            if bad:
+                if len(values) == 1:
+                    self._hardware_error(
+                        f"{self.board.name} pin {bad[0]} does not support PWM. Use pin 3, 5, 6, 9, 10, or 11.", call.span
+                    )
+                self._hardware_error(
+                    f"analogWrite() pin set contains a non-PWM {self.board.name} pin. Use only 3, 5, 6, 9, 10, or 11.", call.span
+                )
+            if set(values) & set(self.board.servo_pwm_conflict_pins):
+                if call.span: self._pwm_timer1_sites.append(call.span)
+            if set(values) & {3, 11}:
+                if call.span: self._pwm_timer2_sites.append(call.span)
+
+    @staticmethod
+    def _servo_attach_bounds_valid(min_us: int, max_us: int) -> bool:
+        # Pinned Servo 1.3.0 stores calibration deltas in int8_t units of 4 us.
+        # Its own source notes the required invariant: abs(delta) / 4 < 128.
+        return (
+            0 < min_us < max_us
+            and abs(544 - min_us) // 4 < 128
+            and abs(2400 - max_us) // 4 < 128
+        )
+
+    def _require_not_all_negative(self, expr: IRExpr, env: dict, message: str, span: SourceSpan | None) -> None:
+        values = self._value_set(expr, env)
+        if values and max(values) < 0:
+            self._hardware_error(message, span)
+
+    def _require_values_within(self, expr: IRExpr, env: dict, low: int, high: int, message: str, span: SourceSpan | None) -> None:
+        values = self._value_set(expr, env)
+        if values and (min(values) < low or max(values) > high):
+            self._hardware_error(message, span)
+
+    def _validate_analog_pin(self, expr: IRExpr, span: SourceSpan | None, env: dict) -> None:
+        if isinstance(expr, IRLoad) and expr.symbol.source_name in self.board.analog_aliases:
+            return
+        values = self._value_set(expr, env)
+        alias_pins = set(self.board.analog_aliases.values())
+        channels = set(self.board.analog_channels)
+        if values is None or not set(values).issubset(channels | alias_pins):
+            self._hardware_error(f"analogRead() pin must be A0..A5 or compatibility channel 0..5 on {self.board.name}.", span)
+        if set(values).issubset(alias_pins):
+            # e.g. `ldr = A0` then `analogRead(ldr)`: the physical analog pin is explicit.
+            return
+        self._warn(
+            "HardwareWarning", "BJ3104",
+            f"analogRead() uses numeric channel 0..5; A0..A5 is clearer on {self.board.name}.", span,
+            "Prefer A0, A1, ... A5 so the physical analog pin is explicit.",
+        )
+
+    def _require_compile_time_pin(self, expr: IRExpr, allowed: Iterable[int], label: str, span: SourceSpan | None, env: dict | None = None) -> int:
+        value = self._single_int(expr, env or self._symbol_values)
+        if value is None:
+            self._hardware_error(f"{label} must be a compile-time pin value on {self.board.name}.", span)
+        if value not in set(allowed):
+            self._hardware_error(f"{label} {self._display_pin(expr, value)} is not valid on {self.board.name}.", span)
+        return value
+
+    def _require_proven_pin(self, expr: IRExpr, allowed: Iterable[int], label: str, span: SourceSpan | None, env: dict) -> None:
+        values = self._value_set(expr, env)
+        allowed_set = set(allowed)
+        if values is None:
+            self._hardware_error(f"{label} must be statically provable as a valid {self.board.name} pin.", span)
+        bad = sorted(set(values) - allowed_set)
+        if bad:
+            rendered = ", ".join(str(x) for x in bad[:6])
+            self._hardware_error(f"{label} contains invalid {self.board.name} pin value(s): {rendered}.", span)
+
+    # ---------- warnings/conflicts ----------
+    def _emit_resource_conflict_warnings(self) -> None:
+        if self._tone_sites and "ir_timer" in self._resources:
+            self._warn(
+                "HardwareWarning", "BJ3111",
+                "tone() and IRRemote may interfere with Timer2/receive timing on Uno. Test separately or avoid combining them.",
+                self._tone_sites[0], "Avoid tone() while reading IR; test the exact library timer settings.",
+            )
+        if self._tone_sites and self._pwm_timer2_sites:
+            self._warn(
+                "HardwareWarning", "BJ3110",
+                "tone() uses Timer2 on Arduino Uno: analogWrite() PWM on D3/D11 may not work normally.",
+                self._pwm_timer2_sites[0], "Use D5, D6, D9 or D10 for PWM while tone() is active.", tuple(self._tone_sites[:2]),
+            )
+        if self._servo_attach_sites and self._pwm_timer1_sites:
+            self._warn(
+                "HardwareWarning", "BJ3101",
+                f"Servo on {self.board.name} uses Timer1; PWM on pins 9 and 10 will not behave normally.",
+                self._pwm_timer1_sites[0], "Use PWM pin 3, 5, 6, or 11 while Servo is active.", tuple(self._servo_attach_sites[:2]),
+            )
+        if self._serial_sites and self._serial_pin_sites:
+            self._warn(
+                "HardwareWarning", "BJ3102",
+                "Serial is active while pin 0 or 1 is also used as general digital I/O (RX/TX conflict).",
+                self._serial_pin_sites[0], "Avoid pins 0 and 1 when using Serial/upload/monitor.", tuple(self._serial_sites[:2]),
+            )
+        if self._i2c_sites and self._i2c_pin_sites:
+            self._warn(
+                "HardwareWarning", "BJ3103",
+                "I2C is active while A4 or A5 is also used independently (SDA/SCL conflict).",
+                self._i2c_pin_sites[0], "Keep A4/A5 dedicated to I2C while Wire/LCD is active.", tuple(self._i2c_sites[:2]),
+            )
+
+    def _validate_servo_capacity(self) -> None:
+        # Pinned Servo 1.3.0 allocates the servoIndex in Servo::Servo(), not in
+        # attach().  Therefore the hard limit applies to constructed Servo
+        # objects even if some are never attached or are later detached.
+        servo_objects = [obj for obj in self.ir.objects if obj.class_name == "Servo"]
+        if len(servo_objects) > self.board.servo_max_channels:
+            bad = servo_objects[self.board.servo_max_channels]
+            self._hardware_error(
+                f"{self.board.name} supports at most {self.board.servo_max_channels} Servo objects with the pinned Servo library.",
+                bad.span,
+                "Create no more than 12 Servo() objects on Arduino Uno; the library assigns the channel index in each constructor.",
+            )
+
+    # ---------- memory ----------
+    def _estimate_static_sram(self) -> int:
+        total = 0
+        for decl in self.ir.storages:
+            if decl.storage not in {StorageClass.MODULE_CONSTANT, StorageClass.PERSISTENT_MODULE}:
+                # setup()/loop() fixed lists are emitted with static storage by the
+                # backend, so they occupy SRAM exactly like module data.
+                if decl.symbol.type.kind == TypeKind.FIXED_LIST:
+                    total += self._type_size(decl.symbol.type)
+                continue
+            total += self._type_size(decl.symbol.type)
+            if decl.symbol.type.kind == TypeKind.STRING and isinstance(decl.initializer, IRConstant) and isinstance(decl.initializer.value, str):
+                total += len(decl.initializer.value.encode("utf-8")) + 1
+        total += self._function_local_list_sram()
+        # Object and library RAM measured with the pinned 0.6.x Uno toolchain
+        # (arduino:avr 1.8.8 + pinned libraries), so the estimate tracks the
+        # real "Global variables use ..." figure instead of only user data.
+        object_sizes = {"Servo": 3, "Ultrasonic": 11, "DHT": 15, "LiquidCrystal_I2C": 25, "RFID": 55, "IRRemote": 4, "Keypad4x4": 25, "StepperMotor": 48}
+        for obj in self.ir.objects:
+            total += object_sizes.get(obj.class_name, 8)
+        # AVR C/C++ string literals used as general stored values live in data
+        # memory unless the backend deliberately wraps them in F()/PROGMEM.
+        # Count those bytes (including the NUL terminator) while excluding the
+        # direct print/Serial/LCD literal paths that the backend flash-backs.
+        total += self._stored_string_literal_sram()
+        classes = {obj.class_name for obj in self.ir.objects}
+        total += 9  # Arduino core (millis timer state)
+        if "uart" in self._resources or "DHT" in classes:  # DHT library links HardwareSerial
+            total += 179
+        if "i2c" in self._resources:
+            total += 216
+        if "timer1" in self._resources or "Servo" in classes:
+            total += 38
+        return total
+
+    def _function_local_list_sram(self) -> int:
+        """Fixed lists local to user functions (static storage in the backend)."""
+        from dataclasses import fields, is_dataclass
+        from .symbols import SymbolKind
+
+        seen: dict[object, int] = {}
+
+        def walk(value) -> None:
+            if isinstance(value, IRStore) and value.target.kind == SymbolKind.LOCAL and value.target.type.kind == TypeKind.FIXED_LIST:
+                seen.setdefault(value.target.symbol_id, self._type_size(value.target.type))
+            if is_dataclass(value) and not isinstance(value, type):
+                for f in fields(value):
+                    walk(getattr(value, f.name))
+            elif isinstance(value, (tuple, list)):
+                for item in value:
+                    walk(item)
+
+        for fn in self.ir.functions:
+            walk(fn.body)
+        return sum(seen.values())
+
+    def _stored_string_literal_sram(self) -> int:
+        total = 0
+
+        def add_text(text: str) -> None:
+            nonlocal total
+            total += len(text.encode("utf-8")) + 1
+
+        def visit_output_expr(expr: IRExpr) -> None:
+            # These exact shapes are emitted through F()/flash-backed output.
+            if isinstance(expr, IRConstant) and isinstance(expr.value, str):
+                return
+            if isinstance(expr, IRFormatString):
+                for part in expr.parts:
+                    if not isinstance(part, str):
+                        visit_expr(part.value)
+                return
+            visit_expr(expr)
+
+        def visit_expr(expr: IRExpr) -> None:
+            if isinstance(expr, IRConstant):
+                if isinstance(expr.value, str):
+                    add_text(expr.value)
+                return
+            if isinstance(expr, IRLoad):
+                return
+            if isinstance(expr, IRListLiteral):
+                for item in expr.elements:
+                    visit_expr(item)
+                return
+            if isinstance(expr, IRIndex):
+                visit_expr(expr.collection); visit_expr(expr.index); return
+            if isinstance(expr, IRUnary):
+                visit_expr(expr.operand); return
+            if isinstance(expr, IRBinary):
+                visit_expr(expr.left); visit_expr(expr.right); return
+            if isinstance(expr, IRCompareChain):
+                for item in expr.operands: visit_expr(item)
+                return
+            if isinstance(expr, IRBool):
+                for item in expr.values: visit_expr(item)
+                return
+            if isinstance(expr, IRConditional):
+                visit_expr(expr.condition); visit_expr(expr.when_true); visit_expr(expr.when_false); return
+            if isinstance(expr, IRFormatString):
+                # A format string only appears in output in valid V1 IR. Literal
+                # segments are flash-backed; formatted expressions may still
+                # contain general string literals.
+                for part in expr.parts:
+                    if not isinstance(part, str): visit_expr(part.value)
+                return
+            if isinstance(expr, IRCall):
+                direct_flash_output = (
+                    len(expr.args) == 1
+                    and (
+                        (expr.kind == IRCallKind.SINGLETON_METHOD and expr.owner_name == "Serial" and expr.method_name in {"print", "println"})
+                        or (
+                            expr.kind == IRCallKind.OBJECT_METHOD
+                            and expr.owner_symbol is not None
+                            and expr.owner_symbol.type.hardware_class == "LiquidCrystal_I2C"
+                            and expr.method_name == "print"
+                        )
+                    )
+                )
+                for i, arg in enumerate(expr.args):
+                    if direct_flash_output and i == 0:
+                        visit_output_expr(arg)
+                    else:
+                        visit_expr(arg)
+                return
+
+        def visit_stmts(stmts: tuple[IRStmt, ...]) -> None:
+            for stmt in stmts:
+                if isinstance(stmt, IRPrint):
+                    for expr in stmt.values: visit_output_expr(expr)
+                elif isinstance(stmt, IRExprStmt): visit_expr(stmt.expression)
+                elif isinstance(stmt, IRStore): visit_expr(stmt.value)
+                elif isinstance(stmt, IRIndexStore): visit_expr(stmt.index); visit_expr(stmt.value)
+                elif isinstance(stmt, IRAugStore): visit_expr(stmt.value)
+                elif isinstance(stmt, IRIf): visit_expr(stmt.condition); visit_stmts(stmt.body); visit_stmts(stmt.otherwise)
+                elif isinstance(stmt, IRWhile): visit_expr(stmt.condition); visit_stmts(stmt.body)
+                elif isinstance(stmt, IRRangeLoop): visit_expr(stmt.start); visit_expr(stmt.stop); visit_expr(stmt.step); visit_stmts(stmt.body)
+                elif isinstance(stmt, IRFixedListLoop):
+                    if stmt.index_start is not None: visit_expr(stmt.index_start)
+                    visit_stmts(stmt.body)
+                elif isinstance(stmt, IRReturn) and stmt.value is not None: visit_expr(stmt.value)
+
+        for decl in self.ir.storages:
+            if decl.initializer is not None:
+                visit_expr(decl.initializer)
+        for obj in self.ir.objects:
+            for arg in obj.args: visit_expr(arg)
+        visit_stmts(self.ir.setup)
+        visit_stmts(self.ir.main_loop)
+        for fn in self.ir.functions: visit_stmts(fn.body)
+        return total
+
+    def _type_size(self, typ: BarmajaType) -> int:
+        if typ.kind in {TypeKind.INT, TypeKind.FLOAT, TypeKind.TIME_U32}: return 4
+        if typ.kind == TypeKind.BOOL: return 1
+        if typ.kind == TypeKind.STRING: return 2  # AVR pointer; stored literal counted separately.
+        if typ.kind == TypeKind.FIXED_LIST:
+            if typ.element_type is None or typ.length is None: return 0
+            return self._type_size(typ.element_type) * typ.length
+        return 0
+
+    # Stack headroom measured on the pinned toolchain (avr-gcc 7.3 + arduino:avr
+    # 1.8.8, simavr ATmega328P). Worker-A stack paint measured the final float32
+    # formatter at 275 B total from RAMEND on the extreme path; static call-frame
+    # analysis gave a 285 B conservative worst case including the UART ISR. Keep a
+    # 320 B minimum whenever heavy float formatting is reachable, while ordinary
+    # sketches retain the smaller base reserve. User-call depth is additive.
+    _STACK_BASE_RESERVE = 160
+    _STACK_FLOAT_FORMAT_RESERVE = 320
+    _STACK_PER_CALL_LEVEL = 16
+
+    def _stack_reserve(self) -> int:
+        from dataclasses import fields, is_dataclass
+
+        functions = {fn.symbol.symbol_id: fn for fn in self.ir.functions}
+
+        def heavy(value) -> bool:
+            # float32 output/rounding helpers use large frames plus 64-bit libgcc calls
+            if isinstance(value, IRPrint) and any(v.type.kind == TypeKind.FLOAT for v in value.values):
+                return True
+            if isinstance(value, IRFormatString) and any(
+                not isinstance(p, str) and (p.precision is not None or p.value.type.kind == TypeKind.FLOAT) for p in value.parts
+            ):
+                return True
+            if isinstance(value, IRCall) and value.kind == IRCallKind.BUILTIN and value.name == "round" and len(value.args) == 2:
+                return True
+            if is_dataclass(value) and not isinstance(value, type):
+                return any(heavy(getattr(value, f.name)) for f in fields(value))
+            if isinstance(value, (tuple, list)):
+                return any(heavy(item) for item in value)
+            return False
+
+        depth_cache: dict[object, int] = {}
+
+        def calls(value, out: set) -> None:
+            if isinstance(value, IRCall) and value.kind == IRCallKind.USER_FUNCTION and value.function_symbol is not None:
+                out.add(value.function_symbol.symbol_id)
+            if is_dataclass(value) and not isinstance(value, type):
+                for f in fields(value):
+                    calls(getattr(value, f.name), out)
+            elif isinstance(value, (tuple, list)):
+                for item in value:
+                    calls(item, out)
+
+        def depth(fid, stack=()) -> int:
+            if fid in depth_cache:
+                return depth_cache[fid]
+            if fid in stack or fid not in functions:
+                return 0
+            callees: set = set()
+            calls(functions[fid].body, callees)
+            d = 1 + max((depth(c, stack + (fid,)) for c in callees), default=0)
+            depth_cache[fid] = d
+            return d
+
+        roots: set = set()
+        calls(self.ir.setup, roots)
+        calls(self.ir.main_loop, roots)
+        max_depth = max((depth(f) for f in roots), default=0)
+        reserve = self._STACK_BASE_RESERVE + self._STACK_PER_CALL_LEVEL * max_depth
+        heavy_reachable = heavy(self.ir.setup) or heavy(self.ir.main_loop) or any(heavy(fn.body) for fn in self.ir.functions)
+        if heavy_reachable:
+            reserve = max(reserve, self._STACK_FLOAT_FORMAT_RESERVE + self._STACK_PER_CALL_LEVEL * max_depth)
+        return reserve
+
+    def _validate_memory(self, estimate: int) -> None:
+        ratio = estimate / self.board.sram_bytes if self.board.sram_bytes else 0.0
+        reserve = self._stack_reserve()
+        if ratio < self.board.sram_error_ratio and self.board.sram_bytes and estimate + reserve > self.board.sram_bytes:
+            raise HardwareError(
+                f"This program needs about {estimate} of the {self.board.sram_bytes} bytes of {self.board.name} RAM/SRAM for its data, "
+                f"and about {reserve} more bytes of stack for its function calls and number printing. "
+                "The board would run out of memory while running. Use shorter lists/strings or fewer nested function calls.",
+                details="Stack reserve measured on the pinned Uno toolchain; see target._stack_reserve().",
+            )
+        if ratio >= self.board.sram_error_ratio:
+            raise HardwareError(
+                f"This program needs about {estimate} of the {self.board.sram_bytes} bytes of {self.board.name} RAM/SRAM ({ratio:.0%}); "
+                f"above {self.board.sram_error_ratio:.0%} the board can crash while running. Use shorter lists/strings or fewer libraries.",
+                details="Estimate includes user data plus measured core/library RAM; the stack needs the remaining space.",
+            )
+        if ratio >= self.board.sram_warning_ratio:
+            self._warn(
+                "MemoryWarning", "BJ3201",
+                f"This program needs about {estimate} of the {self.board.sram_bytes} bytes of {self.board.name} RAM/SRAM ({ratio:.0%}); little memory is left for running.",
+                None, "Reduce large global lists/strings where possible.",
+            )
+
+    # ---------- value facts ----------
+    def _value_set(self, expr: IRExpr, env: dict) -> frozenset[int] | None:
+        if isinstance(expr, IRConstant) and isinstance(expr.value, (int, bool)):
+            return frozenset({int(expr.value)})
+        if isinstance(expr, IRLoad):
+            if expr.symbol.source_name in CONSTANT_VALUES:
+                return frozenset({CONSTANT_VALUES[expr.symbol.source_name]})
+            known = env.get(expr.symbol.symbol_id) or self._symbol_values.get(expr.symbol.symbol_id)
+            if known is not None:
+                return known
+            fact = self.numeric.range_for_symbol_id(expr.symbol.symbol_id)
+            if fact.known and fact.maximum - fact.minimum <= 63:
+                return frozenset(range(fact.minimum, fact.maximum + 1))
+            return None
+        if isinstance(expr, IRIndex) and isinstance(expr.collection, IRLoad):
+            # Any element of a list whose every possible element value is known,
+            # e.g. digitalWrite(leds[k % 5], HIGH) with leds = [2, 3, 4, 5, 6].
+            values = self._list_values.get(expr.collection.symbol.symbol_id)
+            return values if values else None
+        if isinstance(expr, IRListLiteral):
+            out: set[int] = set()
+            for item in expr.elements:
+                values = self._value_set(item, env)
+                if values is None: return None
+                out.update(values)
+                if len(out) > 64: return None
+            return frozenset(out)
+        if isinstance(expr, IRUnary) and expr.op == IRUnaryOp.NEGATE and expr.type.kind == TypeKind.INT:
+            inner = self._value_set(expr.operand, env)
+            return frozenset(-v for v in inner) if inner is not None else None
+        if (
+            isinstance(expr, IRBinary)
+            and expr.type.kind == TypeKind.INT
+            and expr.op in {IRBinaryOp.ADD, IRBinaryOp.SUBTRACT, IRBinaryOp.MULTIPLY, IRBinaryOp.MODULO}
+        ):
+            # Exact small value-set arithmetic, e.g. `pinMode(i + 2, OUTPUT)` inside
+            # `for i in range(5)`, or `digitalWrite(13, 1 + 1)`.  Any result that would
+            # trap at run time (Int32 overflow, modulo by zero) makes the set unknown,
+            # so the backend's runtime guard remains the authority for it.
+            left = self._value_set(expr.left, env)
+            right = self._value_set(expr.right, env)
+            if left is None or right is None or len(left) * len(right) > 4096:
+                return None
+            out_values: set[int] = set()
+            for a in left:
+                for b in right:
+                    if expr.op == IRBinaryOp.ADD:
+                        value = a + b
+                    elif expr.op == IRBinaryOp.SUBTRACT:
+                        value = a - b
+                    elif expr.op == IRBinaryOp.MULTIPLY:
+                        value = a * b
+                    else:
+                        if b == 0:
+                            return None
+                        value = a % b  # Python floor-modulo, as generated by _bj_mod_i32
+                    if value < -(2**31) or value > 2**31 - 1:
+                        return None
+                    out_values.add(value)
+                    if len(out_values) > 64:
+                        return None
+            return frozenset(out_values)
+        if isinstance(expr, IRConditional):
+            a = self._value_set(expr.when_true, env); b = self._value_set(expr.when_false, env)
+            if a is not None and b is not None and len(a | b) <= 64: return a | b
+        if isinstance(expr, IRCall) and expr.kind == IRCallKind.USER_FUNCTION and expr.function_symbol is not None:
+            return self._function_return_values.get(expr.function_symbol.symbol_id)
+        return None
+
+    def _single_int(self, expr: IRExpr, env: dict) -> int | None:
+        values = self._value_set(expr, env)
+        if values is not None and len(values) == 1:
+            return next(iter(values))
+        return None
+
+    def _range_values(self, start: IRExpr, stop: IRExpr, step: IRExpr, env: dict) -> frozenset[int] | None:
+        a, b, s = self._single_int(start, env), self._single_int(stop, env), self._single_int(step, env)
+        if a is None or b is None or s in (None, 0): return None
+        values = list(range(a, b, s))
+        if len(values) > 64: return None
+        return frozenset(values)
+
+    @staticmethod
+    def _intersect_env(a: dict, b: dict) -> dict:
+        out = {}
+        for key in a.keys() & b.keys():
+            merged = a[key] | b[key]
+            if len(merged) <= 64:
+                out[key] = merged
+        return out
+
+    def _display_pin(self, expr: IRExpr, value: int) -> str:
+        if isinstance(expr, IRLoad) and expr.symbol.source_name in self.board.analog_aliases:
+            return expr.symbol.source_name
+        return str(value)
+
+    # ---------- diagnostics ----------
+    def _hardware_error(self, message: str, span: SourceSpan | None, hint: str | None = None):
+        raise HardwareError(
+            message,
+            line=span.line if span else None,
+            column=(span.column + 1) if span else None,
+            end_line=span.end_line if span else None,
+            end_column=span.end_column if span else None,
+            details=hint,
+        )
+
+    def _warn(self, category: str, code: str, message: str, span: SourceSpan | None, hint: str | None = None, related: tuple[SourceSpan, ...] = ()) -> None:
+        key = (code, span.line if span else None, span.column if span else None, message)
+        if key in self._diag_keys:
+            return
+        self._diag_keys.add(key)
+        self._diagnostics.append(TargetDiagnostic(category, code, "warning", message, self.ir.source_name, span, hint, related))
+
+
+
+def analyze_target(ir_module: IRModule, numeric: NumericAnalysis, board: BoardProfile) -> TargetPlan:
+    return TargetAnalyzer(ir_module, numeric, board).analyze()