Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/numeric.py

@@ -0,0 +1,748 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+from .errors import NumericRangeError
+from .symbols import SymbolId, SymbolKind
+from .typesys import TypedModule, TypeKind
+
+INT32_MIN = -(2**31)
+INT32_MAX = 2**31 - 1
+UINT32_MAX = 2**32 - 1
+
+
+@dataclass(frozen=True)
+class NumericRange:
+    minimum: int | None = None
+    maximum: int | None = None
+
+    @property
+    def known(self) -> bool:
+        return self.minimum is not None and self.maximum is not None
+
+    @classmethod
+    def exact(cls, value: int) -> "NumericRange":
+        return cls(value, value)
+
+    @classmethod
+    def int32(cls) -> "NumericRange":
+        return cls(INT32_MIN, INT32_MAX)
+
+    @classmethod
+    def time_u32(cls) -> "NumericRange":
+        return cls(0, UINT32_MAX)
+
+    def union(self, other: "NumericRange") -> "NumericRange":
+        if not self.known or not other.known:
+            return NumericRange()
+        return NumericRange(min(self.minimum, other.minimum), max(self.maximum, other.maximum))
+
+    def within(self, minimum: int, maximum: int) -> bool:
+        return self.known and self.minimum >= minimum and self.maximum <= maximum
+
+
+UNKNOWN_RANGE = NumericRange()
+INT32_RANGE = NumericRange.int32()
+TIME_U32_RANGE = NumericRange.time_u32()
+
+
+@dataclass(frozen=True)
+class NumericAnalysis:
+    typed: TypedModule
+    symbol_ranges: dict[SymbolId, NumericRange]
+    expression_ranges: dict[int, NumericRange]
+    checked_int_expressions: frozenset[int]
+    checked_pwm_arguments: frozenset[int]
+    checked_time_thresholds: frozenset[int]
+
+    def range_for_expr(self, node: ast.AST) -> NumericRange:
+        return self.expression_ranges.get(id(node), UNKNOWN_RANGE)
+
+    def range_for_symbol_id(self, symbol_id: SymbolId) -> NumericRange:
+        return self.symbol_ranges.get(symbol_id, UNKNOWN_RANGE)
+
+    def int_expr_needs_runtime_check(self, node: ast.AST) -> bool:
+        return id(node) in self.checked_int_expressions
+
+    def pwm_arg_needs_runtime_check(self, node: ast.AST) -> bool:
+        return id(node) in self.checked_pwm_arguments
+
+    def time_threshold_needs_runtime_check(self, node: ast.AST) -> bool:
+        return id(node) in self.checked_time_thresholds
+
+
+class NumericAnalyzer:
+    """Target-aware Step-8 numeric range analysis for the Uno.
+
+    The analysis is deliberately conservative. A range fact is used only when
+    it is proven for every assignment represented by the supported subset.
+    Unknown dynamic Int arithmetic is lowered through checked runtime helpers.
+    """
+
+    def __init__(self, typed: TypedModule) -> None:
+        self.typed = typed
+        self.resolved = typed.resolved
+        self.tree = self.resolved.frontend.tree
+        self.symbol_ranges: dict[SymbolId, NumericRange] = {}
+        self.expression_ranges: dict[int, NumericRange] = {}
+        self.checked_int_expressions: set[int] = set()
+        self.checked_pwm_arguments: set[int] = set()
+        self.checked_time_thresholds: set[int] = set()
+        self._parents: dict[int, ast.AST] = {}
+        for parent in ast.walk(self.tree):
+            for child in ast.iter_child_nodes(parent):
+                self._parents[id(child)] = parent
+
+    def analyze(self) -> NumericAnalysis:
+        self._validate_integer_literals()
+
+        # A few fixed-point passes are enough for straight-line assignments,
+        # function parameters, and return propagation. Self-updating state is
+        # intentionally widened to the full Int domain.
+        for _ in range(16):
+            before = dict(self.symbol_ranges)
+            self.expression_ranges.clear()
+            self._scan_module(update_symbols=True)
+            if self.symbol_ranges == before:
+                break
+        else:
+            # Not converged: some ranges are still growing through an indirect
+            # cycle (e.g. `y = x * 2; x = y` in loop()) or a long backward chain.
+            # A partially iterated range is an UNDER-approximation, and trusting it
+            # would emit unchecked arithmetic that silently wraps on the Uno.  Widen
+            # every still-changing symbol to its full domain until stable; each
+            # symbol can be widened at most once, so this terminates.
+            while True:
+                before = dict(self.symbol_ranges)
+                self.expression_ranges.clear()
+                self._scan_module(update_symbols=True)
+                changed = [sid for sid, fact in self.symbol_ranges.items() if before.get(sid) != fact]
+                if not changed:
+                    break
+                for sid in changed:
+                    typ = self.typed.symbol_types.get(sid)
+                    self.symbol_ranges[sid] = TIME_U32_RANGE if typ is not None and typ.kind == TypeKind.TIME_U32 else INT32_RANGE
+
+        # Final pass records stable expression facts and runtime-check needs.
+        self.expression_ranges.clear()
+        self.checked_int_expressions.clear()
+        self.checked_pwm_arguments.clear()
+        self.checked_time_thresholds.clear()
+        self._scan_module(update_symbols=False)
+        self._validate_time_comparisons()
+        self._validate_pwm_boundaries()
+
+        return NumericAnalysis(
+            typed=self.typed,
+            symbol_ranges=dict(self.symbol_ranges),
+            expression_ranges=dict(self.expression_ranges),
+            checked_int_expressions=frozenset(self.checked_int_expressions),
+            checked_pwm_arguments=frozenset(self.checked_pwm_arguments),
+            checked_time_thresholds=frozenset(self.checked_time_thresholds),
+        )
+
+    # ---------- literal domain ----------
+    def _validate_integer_literals(self) -> None:
+        for node in ast.walk(self.tree):
+            if isinstance(node, ast.Constant) and isinstance(node.value, float):
+                self._check_float_literal(node)
+                continue
+            if not isinstance(node, ast.Constant) or isinstance(node.value, bool) or not isinstance(node.value, int):
+                continue
+            parent = self._parents.get(id(node))
+            # Python parses -2147483648 as UnaryOp(USub, Constant(2147483648)).
+            if (
+                node.value == 2**31
+                and isinstance(parent, ast.UnaryOp)
+                and isinstance(parent.op, ast.USub)
+                and parent.operand is node
+            ):
+                continue
+            if not (INT32_MIN <= node.value <= INT32_MAX):
+                raise NumericRangeError(
+                    f"Integer literal {node.value} is outside the Barmaja V1 Int range "
+                    f"[{INT32_MIN}, {INT32_MAX}].",
+                    line=getattr(node, "lineno", None),
+                    column=(getattr(node, "col_offset", 0) + 1) if hasattr(node, "col_offset") else None,
+                )
+
+    @staticmethod
+    def _check_float_literal(node: ast.Constant) -> None:
+        """Float literals must be finite Arduino float32 values (about 1.2e-38 .. 3.4e38)."""
+        import math
+        import struct
+        value = node.value
+        problem = None
+        if not math.isfinite(value):
+            problem = "is not a finite number"
+        else:
+            try:
+                as_f32 = struct.unpack("<f", struct.pack("<f", value))[0]
+            except OverflowError:
+                as_f32 = math.inf
+            if math.isinf(as_f32):
+                problem = "is too large for an Arduino float (max about 3.4e38)"
+            elif value != 0.0 and abs(as_f32) < 1.1754943508222875e-38:
+                problem = "is too small for an Arduino float (min about 1.2e-38)"
+        if problem:
+            raise NumericRangeError(
+                f"Float literal {value!r} {problem}.",
+                line=getattr(node, "lineno", None),
+                column=(getattr(node, "col_offset", 0) + 1) if hasattr(node, "col_offset") else None,
+            )
+
+    # ---------- module / statement scan ----------
+    def _scan_module(self, *, update_symbols: bool) -> None:
+        for stmt in self.tree.body:
+            if isinstance(stmt, ast.FunctionDef):
+                continue
+            self._scan_stmt(stmt, update_symbols=update_symbols)
+        for stmt in self.tree.body:
+            if isinstance(stmt, ast.FunctionDef):
+                self._scan_function(stmt, update_symbols=update_symbols)
+
+    def _scan_function(self, fn: ast.FunctionDef, *, update_symbols: bool) -> None:
+        # Parameter ranges derive from all call sites.
+        sig = self.typed.function_signatures[fn.name]
+        if update_symbols:
+            calls = [
+                n for n in ast.walk(self.tree)
+                if isinstance(n, ast.Call) and isinstance(n.func, ast.Name) and n.func.id == fn.name
+            ]
+            for index, param in enumerate(sig.parameters):
+                ranges = []
+                for call in calls:
+                    if index < len(call.args):
+                        ranges.append(self._expr_range(call.args[index], record_checks=False))
+                if ranges:
+                    merged = ranges[0]
+                    for item in ranges[1:]:
+                        merged = merged.union(item)
+                    self._merge_symbol(param.symbol_id, merged)
+        for stmt in fn.body:
+            self._scan_stmt(stmt, update_symbols=update_symbols)
+
+    def _scan_stmt(self, stmt: ast.stmt, *, update_symbols: bool) -> None:
+        if isinstance(stmt, (ast.ImportFrom, ast.Import, ast.Pass, ast.Global, ast.Break, ast.Continue)):
+            return
+        if isinstance(stmt, ast.Expr):
+            self._expr_range(stmt.value)
+            return
+        if isinstance(stmt, ast.Assign):
+            value_range = self._expr_range(stmt.value)
+            for target in stmt.targets:
+                if isinstance(target, ast.Subscript):
+                    # values[i * k] = x: the store index is an Int expression too.
+                    self._expr_range(target.slice)
+                self._assign_target(target, value_range, stmt.value, update_symbols)
+            return
+        if isinstance(stmt, ast.AugAssign):
+            target_range = self._expr_range(stmt.target)
+            value_range = self._expr_range(stmt.value)
+            if isinstance(stmt.target, ast.Name):
+                sym = self.resolved.symbol_for_name(stmt.target)
+                typ = self.typed.symbol_types.get(sym.symbol_id)
+                if typ and typ.kind == TypeKind.INT and isinstance(stmt.op, (ast.Add, ast.Sub, ast.Mult)):
+                    candidate = self._int_augop_range(stmt.op, target_range, value_range)
+                    if candidate is not None:
+                        lo, hi = candidate
+                        if (
+                            lo < INT32_MIN or hi > INT32_MAX
+                        ) and target_range.known and value_range.known and target_range.minimum == target_range.maximum and value_range.minimum == value_range.maximum:
+                            raise self._overflow(stmt, f"constant augmented integer result [{lo}, {hi}]")
+                if update_symbols and typ and typ.kind == TypeKind.INT:
+                    # Augmented state can execute repeatedly (especially in loop()),
+                    # so keep the post-operation symbol conservative after validating
+                    # any deterministic first-operation overflow above.
+                    self.symbol_ranges[sym.symbol_id] = INT32_RANGE
+            return
+        if isinstance(stmt, ast.If):
+            self._expr_range(stmt.test)
+            for child in stmt.body:
+                self._scan_stmt(child, update_symbols=update_symbols)
+            for child in stmt.orelse:
+                self._scan_stmt(child, update_symbols=update_symbols)
+            return
+        if isinstance(stmt, ast.While):
+            self._expr_range(stmt.test)
+            for child in stmt.body:
+                self._scan_stmt(child, update_symbols=update_symbols)
+            return
+        if isinstance(stmt, ast.For):
+            iter_range = self._range_target_fact(stmt.iter)
+            if update_symbols and isinstance(stmt.target, ast.Name):
+                sym = self.resolved.symbol_for_name(stmt.target)
+                self._merge_symbol(sym.symbol_id, iter_range)
+            if isinstance(stmt.iter, ast.Call):
+                for arg in stmt.iter.args:
+                    self._expr_range(arg)
+            for child in stmt.body:
+                self._scan_stmt(child, update_symbols=update_symbols)
+            return
+        if isinstance(stmt, ast.Return):
+            if stmt.value is not None:
+                self._expr_range(stmt.value)
+            return
+
+    def _assign_target(self, target: ast.AST, value_range: NumericRange, value: ast.AST, update_symbols: bool) -> None:
+        if isinstance(target, ast.Name):
+            if not update_symbols:
+                return
+            sym = self.resolved.symbol_for_name(target)
+            typ = self.typed.symbol_types.get(sym.symbol_id)
+            if typ is None or typ.kind not in {TypeKind.INT, TypeKind.TIME_U32}:
+                return
+            # Self-updating assignment can grow across runtime iterations; do
+            # not infer a falsely narrow bound from a few compiler passes.
+            if self._expr_reads_symbol(value, sym.symbol_id):
+                fact = TIME_U32_RANGE if typ.kind == TypeKind.TIME_U32 else INT32_RANGE
+                self.symbol_ranges[sym.symbol_id] = fact
+                return
+            self._merge_symbol(sym.symbol_id, value_range)
+            return
+        if isinstance(target, (ast.Tuple, ast.List)) and isinstance(value, (ast.Tuple, ast.List)):
+            for t, v in zip(target.elts, value.elts):
+                self._assign_target(t, self._expr_range(v), v, update_symbols)
+
+    def _expr_reads_symbol(self, node: ast.AST, symbol_id: SymbolId) -> bool:
+        for child in ast.walk(node):
+            if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Load):
+                try:
+                    if self.resolved.symbol_for_name(child).symbol_id == symbol_id:
+                        return True
+                except KeyError:
+                    pass
+        return False
+
+    def _merge_symbol(self, symbol_id: SymbolId, incoming: NumericRange) -> None:
+        if not incoming.known:
+            typ = self.typed.symbol_types.get(symbol_id)
+            if typ and typ.kind == TypeKind.TIME_U32:
+                incoming = TIME_U32_RANGE
+            elif typ and typ.kind == TypeKind.INT:
+                incoming = INT32_RANGE
+            else:
+                return
+        current = self.symbol_ranges.get(symbol_id)
+        self.symbol_ranges[symbol_id] = incoming if current is None else current.union(incoming)
+
+    # ---------- expression ranges ----------
+    def _expr_range(self, node: ast.AST, *, record_checks: bool = True) -> NumericRange:
+        result = self._expr_range_uncached(node, record_checks=record_checks)
+        self.expression_ranges[id(node)] = result
+        return result
+
+    def _expr_range_uncached(self, node: ast.AST, *, record_checks: bool) -> NumericRange:
+        typ = self.typed.expression_types.get(id(node))
+
+        if isinstance(node, ast.Constant):
+            if isinstance(node.value, bool):
+                return NumericRange.exact(int(node.value))
+            if isinstance(node.value, int):
+                return NumericRange.exact(node.value)
+            return UNKNOWN_RANGE
+
+        if isinstance(node, ast.Name):
+            try:
+                sym = self.resolved.symbol_for_name(node)
+            except KeyError:
+                return UNKNOWN_RANGE
+            if sym.kind == SymbolKind.API:
+                constants = {
+                    "LOW": 0, "HIGH": 1,
+                    "A0": 14, "A1": 15, "A2": 16, "A3": 17, "A4": 18, "A5": 19,
+                }
+                if node.id in constants:
+                    return NumericRange.exact(constants[node.id])
+                return UNKNOWN_RANGE
+            if typ and typ.kind == TypeKind.TIME_U32:
+                return self.symbol_ranges.get(sym.symbol_id, TIME_U32_RANGE)
+            if typ and typ.kind == TypeKind.INT:
+                return self.symbol_ranges.get(sym.symbol_id, INT32_RANGE)
+            return UNKNOWN_RANGE
+
+        if isinstance(node, ast.UnaryOp):
+            if isinstance(node.op, ast.USub):
+                if isinstance(node.operand, ast.Constant) and isinstance(node.operand.value, int) and not isinstance(node.operand.value, bool):
+                    value = -node.operand.value
+                    if not (INT32_MIN <= value <= INT32_MAX):
+                        raise self._overflow(node, f"Unary '-' result {value}")
+                    return NumericRange.exact(value)
+                operand = self._expr_range(node.operand, record_checks=record_checks)
+                if typ and typ.kind == TypeKind.INT:
+                    if operand.known:
+                        if operand.minimum == operand.maximum == INT32_MIN:
+                            raise self._overflow(node, "Unary '-' result 2147483648")
+                        if operand.minimum <= INT32_MIN <= operand.maximum:
+                            if record_checks:
+                                self.checked_int_expressions.add(id(node))
+                            return INT32_RANGE
+                        return NumericRange(-operand.maximum, -operand.minimum)
+                    if record_checks:
+                        self.checked_int_expressions.add(id(node))
+                    return INT32_RANGE
+            self._expr_range(node.operand, record_checks=record_checks)
+            return UNKNOWN_RANGE
+
+        if isinstance(node, ast.BinOp):
+            left = self._expr_range(node.left, record_checks=record_checks)
+            right = self._expr_range(node.right, record_checks=record_checks)
+            if typ and typ.kind == TypeKind.TIME_U32 and isinstance(node.op, ast.Sub):
+                return TIME_U32_RANGE
+            if not typ or typ.kind != TypeKind.INT:
+                return UNKNOWN_RANGE
+            if isinstance(node.op, (ast.Add, ast.Sub, ast.Mult)):
+                candidate = self._int_binop_range(node, left, right)
+                if candidate is None:
+                    if record_checks:
+                        self.checked_int_expressions.add(id(node))
+                    return INT32_RANGE
+                lo, hi = candidate
+                if lo < INT32_MIN or hi > INT32_MAX:
+                    if left.known and right.known and left.minimum == left.maximum and right.minimum == right.maximum:
+                        raise self._overflow(node, f"constant integer result [{lo}, {hi}]")
+                    if record_checks:
+                        self.checked_int_expressions.add(id(node))
+                    return INT32_RANGE
+                return NumericRange(lo, hi)
+            # Division/modulo semantics and their runtime checks are Step 10.
+            return INT32_RANGE
+
+        if isinstance(node, ast.IfExp):
+            self._expr_range(node.test, record_checks=record_checks)
+            a = self._expr_range(node.body, record_checks=record_checks)
+            b = self._expr_range(node.orelse, record_checks=record_checks)
+            return a.union(b)
+
+        if isinstance(node, ast.BoolOp):
+            for value in node.values:
+                self._expr_range(value, record_checks=record_checks)
+            return NumericRange(0, 1)
+
+        if isinstance(node, ast.Compare):
+            self._expr_range(node.left, record_checks=record_checks)
+            for value in node.comparators:
+                self._expr_range(value, record_checks=record_checks)
+            return NumericRange(0, 1)
+
+        if isinstance(node, ast.Call):
+            for arg in node.args:
+                self._expr_range(arg, record_checks=record_checks)
+            return self._call_range(node)
+
+        if isinstance(node, ast.JoinedStr):
+            for part in node.values:
+                if isinstance(part, ast.FormattedValue):
+                    self._expr_range(part.value, record_checks=record_checks)
+            return UNKNOWN_RANGE
+
+        if isinstance(node, ast.Subscript):
+            # The index expression must be analyzed like any other Int expression:
+            # skipping it left arithmetic such as values[(a * b) % n] UNCHECKED, so an
+            # Int32 overflow silently wrapped and selected the wrong element.
+            self._expr_range(node.value, record_checks=record_checks)
+            self._expr_range(node.slice, record_checks=record_checks)
+            if typ and typ.kind == TypeKind.INT:
+                return INT32_RANGE
+            return UNKNOWN_RANGE
+
+        if isinstance(node, ast.List):
+            # Elements of a list literal are ordinary expressions (checked arithmetic).
+            for item in node.elts:
+                self._expr_range(item, record_checks=record_checks)
+            return UNKNOWN_RANGE
+
+        # Closed-subset safety net: never leave a nested expression unanalyzed,
+        # because "not analyzed" would mean "not checked" for its Int arithmetic.
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, ast.expr):
+                self._expr_range(child, record_checks=record_checks)
+        return UNKNOWN_RANGE
+
+    def _int_binop_range(self, node: ast.BinOp, left: NumericRange, right: NumericRange) -> tuple[int, int] | None:
+        return self._int_augop_range(node.op, left, right)
+
+    @staticmethod
+    def _int_augop_range(op: ast.operator, left: NumericRange, right: NumericRange) -> tuple[int, int] | None:
+        if not left.known or not right.known:
+            return None
+        a, b, c, d = left.minimum, left.maximum, right.minimum, right.maximum
+        if isinstance(op, ast.Add):
+            return a + c, b + d
+        if isinstance(op, ast.Sub):
+            return a - d, b - c
+        if isinstance(op, ast.Mult):
+            values = (a * c, a * d, b * c, b * d)
+            return min(values), max(values)
+        return None
+
+    def _call_range(self, node: ast.Call) -> NumericRange:
+        if isinstance(node.func, ast.Name):
+            name = node.func.id
+            if name == "analogRead":
+                return NumericRange(0, 1023)
+            if name == "digitalRead":
+                return NumericRange(0, 1)
+            if name == "millis":
+                return TIME_U32_RANGE
+            if name == "bool":
+                return NumericRange(0, 1)
+            if name == "abs" and node.args:
+                arg = self.expression_ranges.get(id(node.args[0]), UNKNOWN_RANGE)
+                arg_type = self.typed.expression_types.get(id(node.args[0]))
+                if arg_type and arg_type.kind == TypeKind.INT and arg.known:
+                    if arg.minimum == arg.maximum == INT32_MIN:
+                        raise self._overflow(node, "abs() result 2147483648")
+                    if arg.minimum <= INT32_MIN <= arg.maximum:
+                        return INT32_RANGE
+                    return NumericRange(0, max(abs(arg.minimum), abs(arg.maximum)))
+                return INT32_RANGE
+            if name in {"min", "max"} and node.args:
+                facts = [self.expression_ranges.get(id(x), UNKNOWN_RANGE) for x in node.args]
+                if all(x.known for x in facts):
+                    if name == "min":
+                        return NumericRange(min(x.minimum for x in facts), min(x.maximum for x in facts))
+                    return NumericRange(max(x.minimum for x in facts), max(x.maximum for x in facts))
+            if name == "int" and node.args:
+                arg_type = self.typed.expression_types.get(id(node.args[0]))
+                if arg_type and arg_type.kind == TypeKind.INT:
+                    return self.expression_ranges.get(id(node.args[0]), INT32_RANGE)
+                if arg_type and arg_type.kind == TypeKind.FLOAT:
+                    value = self._literal_float32(node.args[0])
+                    if value is not None:
+                        converted = int(value)
+                        if not (INT32_MIN <= converted <= INT32_MAX):
+                            raise self._overflow(node, f"int() result {converted}")
+                        return NumericRange.exact(converted)
+                return INT32_RANGE
+            if name == "round" and node.args:
+                arg_type = self.typed.expression_types.get(id(node.args[0]))
+                # round(Int) is identity; round(Int, ndigits) is exactly
+                # constant-foldable when both inputs are literals/range-exact.
+                if arg_type and arg_type.kind == TypeKind.INT:
+                    arg = self.expression_ranges.get(id(node.args[0]), UNKNOWN_RANGE)
+                    if arg.known and arg.minimum == arg.maximum:
+                        value = arg.minimum
+                        ndigits = self._literal_int(node.args[1]) if len(node.args) == 2 else None
+                        result = value if len(node.args) == 1 else round(value, ndigits)
+                        if not (INT32_MIN <= result <= INT32_MAX):
+                            raise self._overflow(node, f"round() result {result}")
+                        return NumericRange.exact(result)
+                # One-argument round(Float) returns Int. Literal floats are
+                # first narrowed to the target float32 value, matching Uno.
+                if arg_type and arg_type.kind == TypeKind.FLOAT and len(node.args) == 1:
+                    value = self._literal_float32(node.args[0])
+                    if value is not None:
+                        result = round(value)
+                        if not (INT32_MIN <= result <= INT32_MAX):
+                            raise self._overflow(node, f"round() result {result}")
+                        return NumericRange.exact(result)
+                return INT32_RANGE
+            if name == "sum" and node.args:
+                arg_type = self.typed.expression_types.get(id(node.args[0]))
+                if arg_type and arg_type.kind == TypeKind.FIXED_LIST and arg_type.element_type and arg_type.element_type.kind == TypeKind.INT:
+                    values = self._constant_fixed_int_list(node.args[0])
+                    if values is not None:
+                        total = 0
+                        for value in values:
+                            total += value
+                            if not (INT32_MIN <= total <= INT32_MAX):
+                                raise self._overflow(node, f"sum() intermediate result {total}")
+                        return NumericRange.exact(total)
+                return INT32_RANGE
+            if name in self.typed.function_signatures:
+                # Union ranges of return expressions from the function body.
+                fn = next((x for x in self.tree.body if isinstance(x, ast.FunctionDef) and x.name == name), None)
+                if fn is not None:
+                    ranges = [self._expr_range(x.value, record_checks=False) for x in ast.walk(fn) if isinstance(x, ast.Return) and x.value is not None]
+                    if ranges:
+                        merged = ranges[0]
+                        for item in ranges[1:]:
+                            merged = merged.union(item)
+                        return merged
+        if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            owner, method = node.func.value.id, node.func.attr
+            if owner == "Serial":
+                if method == "available":
+                    return NumericRange(0, INT32_MAX)
+                if method == "read":
+                    return NumericRange(-1, 255)
+            if owner == "Wire":
+                if method == "available":
+                    return NumericRange(0, INT32_MAX)
+                if method == "read":
+                    return NumericRange(-1, 255)
+            try:
+                owner_sym = self.resolved.symbol_for_name(node.func.value)
+                owner_type = self.typed.symbol_types.get(owner_sym.symbol_id)
+            except KeyError:
+                owner_type = None
+            if owner_type and owner_type.kind == TypeKind.HARDWARE:
+                if owner_type.hardware_class == "Servo" and method == "read":
+                    return NumericRange(0, 180)
+                if owner_type.hardware_class == "Servo" and method == "attached":
+                    return NumericRange(0, 1)
+                if owner_type.hardware_class == "Ultrasonic" and method == "read":
+                    return NumericRange(0, INT32_MAX)
+        typ = self.typed.expression_types.get(id(node))
+        if typ and typ.kind == TypeKind.TIME_U32:
+            return TIME_U32_RANGE
+        if typ and typ.kind == TypeKind.INT:
+            return INT32_RANGE
+        return UNKNOWN_RANGE
+
+    def _range_target_fact(self, iter_node: ast.AST) -> NumericRange:
+        if not isinstance(iter_node, ast.Call) or not isinstance(iter_node.func, ast.Name) or iter_node.func.id != "range":
+            return INT32_RANGE
+        args = iter_node.args
+        try:
+            values = [self._literal_int(x) for x in args]
+        except ValueError:
+            return INT32_RANGE
+        if any(v is None for v in values):
+            return INT32_RANGE
+        if len(values) == 1:
+            start, stop, step = 0, values[0], 1
+        elif len(values) == 2:
+            start, stop, step = values[0], values[1], 1
+        else:
+            start, stop, step = values
+        if step == 0:
+            return INT32_RANGE
+        seq = range(start, stop, step)
+        if len(seq) == 0:
+            return INT32_RANGE
+        first, last = seq[0], seq[-1]
+        return NumericRange(min(first, last), max(first, last))
+
+    @staticmethod
+    def _literal_int(node: ast.AST) -> int | None:
+        if isinstance(node, ast.Constant) and isinstance(node.value, int) and not isinstance(node.value, bool):
+            return node.value
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub) and isinstance(node.operand, ast.Constant) and isinstance(node.operand.value, int):
+            return -node.operand.value
+        return None
+
+    @staticmethod
+    def _literal_float32(node: ast.AST) -> float | None:
+        import struct
+        sign = 1.0
+        value_node = node
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+            sign = -1.0
+            value_node = node.operand
+        if not isinstance(value_node, ast.Constant) or not isinstance(value_node.value, float):
+            return None
+        try:
+            return sign * struct.unpack("<f", struct.pack("<f", float(value_node.value)))[0]
+        except OverflowError:
+            return None
+
+    def _constant_fixed_int_list(self, node: ast.AST) -> list[int] | None:
+        """Return immutable literal Int list contents when proven from source.
+
+        This is intentionally conservative: exactly one whole-list literal
+        assignment and no element stores/rebinds anywhere in the resolved
+        symbol's scope. It exists only to honor the locked compile-time
+        overflow rule for statically foldable sum().
+        """
+        if not isinstance(node, ast.Name):
+            return None
+        try:
+            wanted = self.resolved.symbol_for_name(node).symbol_id
+        except KeyError:
+            return None
+        found: list[int] | None = None
+        whole_assignments = 0
+        for item in ast.walk(self.tree):
+            if isinstance(item, ast.Assign):
+                for target in item.targets:
+                    if isinstance(target, ast.Name):
+                        try:
+                            same = self.resolved.symbol_for_name(target).symbol_id == wanted
+                        except KeyError:
+                            same = False
+                        if same:
+                            whole_assignments += 1
+                            if not isinstance(item.value, ast.List):
+                                return None
+                            vals: list[int] = []
+                            for elt in item.value.elts:
+                                value = self._literal_int(elt)
+                                if value is None:
+                                    return None
+                                vals.append(value)
+                            found = vals
+                    elif isinstance(target, ast.Subscript) and isinstance(target.value, ast.Name):
+                        try:
+                            same = self.resolved.symbol_for_name(target.value).symbol_id == wanted
+                        except KeyError:
+                            same = False
+                        if same:
+                            return None
+            elif isinstance(item, ast.AugAssign) and isinstance(item.target, ast.Subscript) and isinstance(item.target.value, ast.Name):
+                try:
+                    same = self.resolved.symbol_for_name(item.target.value).symbol_id == wanted
+                except KeyError:
+                    same = False
+                if same:
+                    return None
+        return found if whole_assignments == 1 else None
+
+    # ---------- target boundary rules ----------
+    def _validate_time_comparisons(self) -> None:
+        for node in ast.walk(self.tree):
+            if not isinstance(node, ast.Compare):
+                continue
+            values = [node.left, *node.comparators]
+            for left, right in zip(values, values[1:]):
+                lt = self.typed.expression_types.get(id(left))
+                rt = self.typed.expression_types.get(id(right))
+                if lt is None or rt is None:
+                    continue
+                if lt.kind == TypeKind.TIME_U32 and rt.kind == TypeKind.INT:
+                    self._validate_time_threshold(right)
+                elif rt.kind == TypeKind.TIME_U32 and lt.kind == TypeKind.INT:
+                    self._validate_time_threshold(left)
+
+    def _validate_time_threshold(self, node: ast.AST) -> None:
+        fact = self.expression_ranges.get(id(node), UNKNOWN_RANGE)
+        if fact.known and fact.maximum < 0:
+            raise NumericRangeError(
+                "TimeU32 comparisons require a non-negative integer threshold.",
+                line=getattr(node, "lineno", None),
+            )
+        if fact.within(0, UINT32_MAX):
+            return
+        self.checked_time_thresholds.add(id(node))
+
+    def _validate_pwm_boundaries(self) -> None:
+        for node in ast.walk(self.tree):
+            if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name) or node.func.id != "analogWrite":
+                continue
+            if len(node.args) < 2:
+                continue
+            value = node.args[1]
+            fact = self.expression_ranges.get(id(value), UNKNOWN_RANGE)
+            if fact.known and (fact.minimum < 0 or fact.maximum > 255):
+                if fact.minimum == fact.maximum:
+                    raise NumericRangeError(
+                        f"analogWrite() value {fact.minimum} is outside the Uno PWM range 0..255.",
+                        line=getattr(value, "lineno", None),
+                    )
+                # A proven partially out-of-range dynamic interval still needs
+                # a runtime boundary check; do not reject useful dynamic code.
+                self.checked_pwm_arguments.add(id(value))
+            elif not fact.within(0, 255):
+                self.checked_pwm_arguments.add(id(value))
+
+    def _overflow(self, node: ast.AST, description: str) -> NumericRangeError:
+        return NumericRangeError(
+            f"{description} is outside the Barmaja V1 signed 32-bit Int range.",
+            line=getattr(node, "lineno", None),
+        )
+
+
+def analyze_numeric_ranges(typed: TypedModule) -> NumericAnalysis:
+    return NumericAnalyzer(typed).analyze()