Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/ir.py

@@ -0,0 +1,660 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, fields, is_dataclass
+from enum import Enum
+from typing import Any
+
+from .errors import InternalCompilerError
+from .flow import StorageClass
+from .source import SourceSpan
+from .symbols import SymbolId, SymbolKind
+from .typesys import BarmajaType, TypeKind
+
+
+class IREffect(Enum):
+    """Target-independent observable expression effects.
+
+    Effects are conservative. They exist so later target/backend phases never
+    need to rediscover whether evaluating an expression can touch hardware,
+    emit output, invoke user code, or fail a Barmaja runtime safety check.
+    """
+
+    HARDWARE_IO = "hardware_io"
+    OUTPUT = "output"
+    USER_CALL = "user_call"
+    MAY_FAIL = "may_fail"
+
+
+class IRUnaryOp(Enum):
+    NEGATE = "negate"
+    NOT = "not"
+
+
+class IRBinaryOp(Enum):
+    ADD = "add"
+    SUBTRACT = "subtract"
+    MULTIPLY = "multiply"
+    TRUE_DIVIDE = "true_divide"
+    MODULO = "modulo"
+
+
+class IRCompareOp(Enum):
+    EQ = "eq"
+    NE = "ne"
+    LT = "lt"
+    LE = "le"
+    GT = "gt"
+    GE = "ge"
+
+
+class IRBoolOp(Enum):
+    AND = "and"
+    OR = "or"
+
+
+class IRCallKind(Enum):
+    USER_FUNCTION = "user_function"
+    API_FUNCTION = "api_function"
+    BUILTIN = "builtin"
+    OBJECT_METHOD = "object_method"
+    SINGLETON_METHOD = "singleton_method"
+
+
+class IRLoopControlTarget(Enum):
+    NESTED_LOOP = "nested_loop"
+    MAIN_LOOP = "main_loop"
+
+
+@dataclass(frozen=True)
+class IRSymbolRef:
+    symbol_id: SymbolId
+    source_name: str
+    backend_name: str
+    kind: SymbolKind
+    type: BarmajaType
+
+
+@dataclass(frozen=True, order=True)
+class IRTempId:
+    value: int
+
+    def __str__(self) -> str:
+        return f"T{self.value:04d}"
+
+
+@dataclass(frozen=True)
+class IRFunctionRef:
+    symbol_id: SymbolId
+    source_name: str
+    backend_name: str
+
+
+@dataclass(frozen=True)
+class IRTempRef:
+    temp_id: IRTempId
+    backend_name: str
+    type: BarmajaType
+    purpose: str
+    span: SourceSpan | None
+
+
+@dataclass(frozen=True)
+class IRExpr:
+    type: BarmajaType
+    span: SourceSpan | None
+    effects: frozenset[IREffect]
+
+
+@dataclass(frozen=True)
+class IRConstant(IRExpr):
+    value: bool | int | float | str
+
+
+@dataclass(frozen=True)
+class IRLoad(IRExpr):
+    symbol: IRSymbolRef
+
+
+@dataclass(frozen=True)
+class IRListLiteral(IRExpr):
+    elements: tuple[IRExpr, ...]
+
+
+@dataclass(frozen=True)
+class IRIndex(IRExpr):
+    collection: IRExpr
+    index: IRExpr
+
+
+@dataclass(frozen=True)
+class IRUnary(IRExpr):
+    op: IRUnaryOp
+    operand: IRExpr
+
+
+@dataclass(frozen=True)
+class IRBinary(IRExpr):
+    op: IRBinaryOp
+    left: IRExpr
+    right: IRExpr
+    checked: bool = False
+
+
+@dataclass(frozen=True)
+class IRCompareChain(IRExpr):
+    """Normalized Python comparison chain.
+
+    ``operand_temps`` are evaluated sequentially.  Later operands are only
+    evaluated after the preceding comparison succeeds, preserving Python
+    short-circuit behavior while guaranteeing each reached operand is evaluated
+    exactly once.
+    """
+
+    operands: tuple[IRExpr, ...]
+    operators: tuple[IRCompareOp, ...]
+    operand_temps: tuple[IRTempRef, ...]
+
+
+@dataclass(frozen=True)
+class IRBool(IRExpr):
+    op: IRBoolOp
+    values: tuple[IRExpr, ...]
+
+
+@dataclass(frozen=True)
+class IRConditional(IRExpr):
+    condition: IRExpr
+    when_true: IRExpr
+    when_false: IRExpr
+
+
+@dataclass(frozen=True)
+class IRCall(IRExpr):
+    kind: IRCallKind
+    name: str
+    args: tuple[IRExpr, ...]
+    function_symbol: IRFunctionRef | None = None
+    owner_symbol: IRSymbolRef | None = None
+    owner_name: str | None = None
+    method_name: str | None = None
+
+
+@dataclass(frozen=True)
+class IRFormattedValue:
+    value: IRExpr
+    precision: int | None
+    span: SourceSpan | None
+
+
+@dataclass(frozen=True)
+class IRFormatString(IRExpr):
+    parts: tuple[str | IRFormattedValue, ...]
+
+
+@dataclass(frozen=True)
+class IRStmt:
+    span: SourceSpan | None
+
+
+@dataclass(frozen=True)
+class IRStore(IRStmt):
+    target: IRSymbolRef
+    value: IRExpr
+
+
+@dataclass(frozen=True)
+class IRIndexStore(IRStmt):
+    collection: IRSymbolRef
+    index: IRExpr
+    value: IRExpr
+
+
+@dataclass(frozen=True)
+class IRAugStore(IRStmt):
+    target: IRSymbolRef
+    op: IRBinaryOp
+    value: IRExpr
+    checked: bool = False
+
+
+@dataclass(frozen=True)
+class IRExprStmt(IRStmt):
+    expression: IRExpr
+
+
+@dataclass(frozen=True)
+class IRPrint(IRStmt):
+    values: tuple[IRExpr, ...]
+    newline: bool = True
+
+
+@dataclass(frozen=True)
+class IRIf(IRStmt):
+    condition: IRExpr
+    body: tuple[IRStmt, ...]
+    otherwise: tuple[IRStmt, ...]
+
+
+@dataclass(frozen=True)
+class IRWhile(IRStmt):
+    condition: IRExpr
+    body: tuple[IRStmt, ...]
+
+
+@dataclass(frozen=True)
+class IRRangeLoop(IRStmt):
+    target: IRSymbolRef
+    iterator_temp: IRTempRef
+    start_temp: IRTempRef
+    stop_temp: IRTempRef
+    step_temp: IRTempRef
+    start: IRExpr
+    stop: IRExpr
+    step: IRExpr
+    body: tuple[IRStmt, ...]
+
+
+@dataclass(frozen=True)
+class IRFixedListLoop(IRStmt):
+    collection: IRSymbolRef
+    value_target: IRSymbolRef
+    index_target: IRSymbolRef | None
+    iterator_temp: IRTempRef
+    index_start: IRExpr | None
+    index_start_temp: IRTempRef | None
+    body: tuple[IRStmt, ...]
+
+
+@dataclass(frozen=True)
+class IRBreak(IRStmt):
+    target: IRLoopControlTarget
+
+
+@dataclass(frozen=True)
+class IRContinue(IRStmt):
+    target: IRLoopControlTarget
+
+
+@dataclass(frozen=True)
+class IRReturn(IRStmt):
+    value: IRExpr | None
+
+
+@dataclass(frozen=True)
+class IRObjectDecl:
+    symbol: IRSymbolRef
+    class_name: str
+    args: tuple[IRExpr, ...]
+    span: SourceSpan | None
+
+
+@dataclass(frozen=True)
+class IRStorageDecl:
+    symbol: IRSymbolRef
+    storage: StorageClass
+    initializer: IRExpr | None
+    span: SourceSpan | None
+
+
+@dataclass(frozen=True)
+class IRFunction:
+    symbol: IRFunctionRef
+    parameters: tuple[IRSymbolRef, ...]
+    return_type: BarmajaType
+    body: tuple[IRStmt, ...]
+    span: SourceSpan | None
+
+
+@dataclass(frozen=True)
+class IRModule:
+    source_name: str
+    storages: tuple[IRStorageDecl, ...]
+    objects: tuple[IRObjectDecl, ...]
+    setup: tuple[IRStmt, ...]
+    main_loop: tuple[IRStmt, ...]
+    functions: tuple[IRFunction, ...]
+    generated_temporaries: tuple[IRTempRef, ...]
+
+
+IR_EXPRESSION_TYPES = (
+    IRConstant, IRLoad, IRListLiteral, IRIndex, IRUnary, IRBinary, IRCompareChain, IRBool,
+    IRConditional, IRCall, IRFormatString,
+)
+
+
+def _walk_values(value: Any):
+    yield value
+    if is_dataclass(value):
+        for f in fields(value):
+            yield from _walk_values(getattr(value, f.name))
+    elif isinstance(value, (tuple, list, frozenset)):
+        for item in value:
+            yield from _walk_values(item)
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            yield from _walk_values(key)
+            yield from _walk_values(item)
+
+
+def validate_ir(module: IRModule) -> None:
+    """Assert the typed-IR boundary invariants.
+
+    Malformed IR is always a compiler defect, never a student diagnostic.  The
+    validator therefore converts structural corruption into a stable
+    ``InternalCompilerError`` before target/backend code can dereference bad
+    fields or silently emit incorrect C++.
+    """
+
+    def fail(message: str) -> None:
+        raise InternalCompilerError(message)
+
+    def require_tuple(value: Any, cls: type, label: str) -> None:
+        if not isinstance(value, tuple) or not all(isinstance(item, cls) for item in value):
+            fail(f"Typed IR field '{label}' must be a tuple of {cls.__name__} values.")
+
+    def require_span(value: Any, label: str) -> None:
+        if not isinstance(value, SourceSpan):
+            fail(f"Typed IR field '{label}' is missing a valid source span.")
+
+    def validate_type(value: Any, label: str) -> None:
+        if not isinstance(value, BarmajaType) or not isinstance(value.kind, TypeKind):
+            fail(f"Typed IR field '{label}' does not contain a valid Barmaja type.")
+        if value.kind == TypeKind.UNKNOWN:
+            fail("Typed IR contains an unresolved Unknown type.")
+        if value.kind == TypeKind.HARDWARE:
+            if not isinstance(value.hardware_class, str) or not value.hardware_class:
+                fail(f"Typed IR field '{label}' contains an incomplete Hardware type.")
+        if value.kind == TypeKind.FIXED_LIST:
+            if not isinstance(value.element_type, BarmajaType) or not isinstance(value.length, int) or value.length <= 0:
+                fail(f"Typed IR field '{label}' contains an incomplete FixedList type.")
+            validate_type(value.element_type, f"{label}.element_type")
+
+    def validate_symbol_ref(value: Any, label: str) -> None:
+        if not isinstance(value, IRSymbolRef):
+            fail(f"Typed IR field '{label}' must contain a symbol reference.")
+        if not isinstance(value.symbol_id, SymbolId):
+            fail(f"Typed IR symbol in '{label}' has an invalid symbol ID.")
+        if not isinstance(value.source_name, str) or not value.source_name:
+            fail(f"Typed IR symbol in '{label}' has an invalid source name.")
+        if not isinstance(value.backend_name, str) or not value.backend_name:
+            fail(f"Typed IR symbol '{value.source_name}' has an invalid backend name.")
+        if not isinstance(value.kind, SymbolKind):
+            fail(f"Typed IR symbol '{value.source_name}' has an invalid symbol kind.")
+        validate_type(value.type, f"{label}.type")
+
+    def validate_function_ref(value: Any, label: str) -> None:
+        if not isinstance(value, IRFunctionRef):
+            fail(f"Typed IR field '{label}' must contain a function reference.")
+        if not isinstance(value.symbol_id, SymbolId):
+            fail(f"Typed IR function in '{label}' has an invalid symbol ID.")
+        if not isinstance(value.source_name, str) or not value.source_name:
+            fail(f"Typed IR function in '{label}' has an invalid source name.")
+        if not isinstance(value.backend_name, str) or not value.backend_name:
+            fail(f"Typed IR function '{value.source_name}' has an invalid backend name.")
+
+    def validate_temp_ref(value: Any, label: str) -> None:
+        if not isinstance(value, IRTempRef):
+            fail(f"Typed IR field '{label}' must contain a temporary reference.")
+        if not isinstance(value.temp_id, IRTempId) or not isinstance(value.temp_id.value, int):
+            fail(f"Typed IR temporary in '{label}' has an invalid temporary ID.")
+        if not isinstance(value.backend_name, str) or not value.backend_name:
+            fail(f"Typed IR temporary in '{label}' has an invalid backend name.")
+        validate_type(value.type, f"{label}.type")
+        if not isinstance(value.purpose, str) or not value.purpose:
+            fail(f"Typed IR temporary in '{label}' has an invalid purpose.")
+        require_span(value.span, f"{label}.span")
+
+    def validate_expr(value: Any, label: str = "expression") -> None:
+        if not isinstance(value, IRExpr):
+            fail(f"Typed IR field '{label}' must contain an IR expression.")
+        validate_type(value.type, f"{label}.type")
+        require_span(value.span, f"{label}.span")
+        if not isinstance(value.effects, frozenset) or not all(isinstance(effect, IREffect) for effect in value.effects):
+            fail(f"Typed IR field '{label}.effects' must be a frozenset of IREffect values.")
+
+        if isinstance(value, IRConstant):
+            if not isinstance(value.value, (bool, int, float, str)):
+                fail("Typed IR constant contains an unsupported value type.")
+        elif isinstance(value, IRLoad):
+            validate_symbol_ref(value.symbol, f"{label}.symbol")
+        elif isinstance(value, IRListLiteral):
+            require_tuple(value.elements, IRExpr, f"{label}.elements")
+            for i, item in enumerate(value.elements):
+                validate_expr(item, f"{label}.elements[{i}]")
+        elif isinstance(value, IRIndex):
+            validate_expr(value.collection, f"{label}.collection")
+            validate_expr(value.index, f"{label}.index")
+        elif isinstance(value, IRUnary):
+            if not isinstance(value.op, IRUnaryOp):
+                fail("Typed IR unary expression has an invalid operator.")
+            validate_expr(value.operand, f"{label}.operand")
+        elif isinstance(value, IRBinary):
+            if not isinstance(value.op, IRBinaryOp):
+                fail("Typed IR binary expression has an invalid operator.")
+            if not isinstance(value.checked, bool):
+                fail("Typed IR binary expression has an invalid checked flag.")
+            validate_expr(value.left, f"{label}.left")
+            validate_expr(value.right, f"{label}.right")
+        elif isinstance(value, IRCompareChain):
+            require_tuple(value.operands, IRExpr, f"{label}.operands")
+            require_tuple(value.operators, IRCompareOp, f"{label}.operators")
+            require_tuple(value.operand_temps, IRTempRef, f"{label}.operand_temps")
+            if len(value.operands) < 2 or len(value.operators) != len(value.operands) - 1:
+                fail("Typed IR comparison chain has inconsistent operand/operator arity.")
+            if len(value.operand_temps) != len(value.operands):
+                fail("Typed IR comparison chain has inconsistent temporary arity.")
+            for i, item in enumerate(value.operands):
+                validate_expr(item, f"{label}.operands[{i}]")
+            for i, temp in enumerate(value.operand_temps):
+                validate_temp_ref(temp, f"{label}.operand_temps[{i}]")
+        elif isinstance(value, IRBool):
+            if not isinstance(value.op, IRBoolOp):
+                fail("Typed IR boolean expression has an invalid operator.")
+            require_tuple(value.values, IRExpr, f"{label}.values")
+            if len(value.values) < 2:
+                fail("Typed IR boolean expression must contain at least two values.")
+            for i, item in enumerate(value.values):
+                validate_expr(item, f"{label}.values[{i}]")
+        elif isinstance(value, IRConditional):
+            validate_expr(value.condition, f"{label}.condition")
+            validate_expr(value.when_true, f"{label}.when_true")
+            validate_expr(value.when_false, f"{label}.when_false")
+        elif isinstance(value, IRCall):
+            if not isinstance(value.kind, IRCallKind):
+                fail("Typed IR call has an invalid call kind.")
+            if not isinstance(value.name, str) or not value.name:
+                fail("Typed IR call has an invalid name.")
+            require_tuple(value.args, IRExpr, f"{label}.args")
+            for i, arg in enumerate(value.args):
+                validate_expr(arg, f"{label}.args[{i}]")
+            if value.function_symbol is not None:
+                validate_function_ref(value.function_symbol, f"{label}.function_symbol")
+            if value.owner_symbol is not None:
+                validate_symbol_ref(value.owner_symbol, f"{label}.owner_symbol")
+            if value.owner_name is not None and not isinstance(value.owner_name, str):
+                fail("Typed IR call owner_name must be text when present.")
+            if value.method_name is not None and not isinstance(value.method_name, str):
+                fail("Typed IR call method_name must be text when present.")
+        elif isinstance(value, IRFormatString):
+            if not isinstance(value.parts, tuple) or not all(isinstance(part, (str, IRFormattedValue)) for part in value.parts):
+                fail("Typed IR format string contains an invalid part.")
+            for i, part in enumerate(value.parts):
+                if isinstance(part, IRFormattedValue):
+                    validate_expr(part.value, f"{label}.parts[{i}].value")
+                    if part.precision is not None and not isinstance(part.precision, int):
+                        fail("Typed IR formatted value precision must be an integer or None.")
+                    require_span(part.span, f"{label}.parts[{i}].span")
+        else:
+            fail(f"Unknown typed IR expression node {type(value).__name__}.")
+
+    def validate_stmt(value: Any, label: str = "statement") -> None:
+        if not isinstance(value, IRStmt):
+            fail(f"Typed IR field '{label}' must contain an IR statement.")
+        require_span(value.span, f"{label}.span")
+
+        if isinstance(value, IRStore):
+            validate_symbol_ref(value.target, f"{label}.target")
+            validate_expr(value.value, f"{label}.value")
+        elif isinstance(value, IRIndexStore):
+            validate_symbol_ref(value.collection, f"{label}.collection")
+            validate_expr(value.index, f"{label}.index")
+            validate_expr(value.value, f"{label}.value")
+        elif isinstance(value, IRAugStore):
+            validate_symbol_ref(value.target, f"{label}.target")
+            if not isinstance(value.op, IRBinaryOp) or not isinstance(value.checked, bool):
+                fail("Typed IR augmented store has an invalid operator/checked flag.")
+            validate_expr(value.value, f"{label}.value")
+        elif isinstance(value, IRExprStmt):
+            validate_expr(value.expression, f"{label}.expression")
+        elif isinstance(value, IRPrint):
+            require_tuple(value.values, IRExpr, f"{label}.values")
+            if not isinstance(value.newline, bool):
+                fail("Typed IR print newline flag must be boolean.")
+            for i, expr in enumerate(value.values):
+                validate_expr(expr, f"{label}.values[{i}]")
+        elif isinstance(value, IRIf):
+            validate_expr(value.condition, f"{label}.condition")
+            require_tuple(value.body, IRStmt, f"{label}.body")
+            require_tuple(value.otherwise, IRStmt, f"{label}.otherwise")
+            for i, stmt in enumerate(value.body):
+                validate_stmt(stmt, f"{label}.body[{i}]")
+            for i, stmt in enumerate(value.otherwise):
+                validate_stmt(stmt, f"{label}.otherwise[{i}]")
+        elif isinstance(value, IRWhile):
+            validate_expr(value.condition, f"{label}.condition")
+            require_tuple(value.body, IRStmt, f"{label}.body")
+            for i, stmt in enumerate(value.body):
+                validate_stmt(stmt, f"{label}.body[{i}]")
+        elif isinstance(value, IRRangeLoop):
+            validate_symbol_ref(value.target, f"{label}.target")
+            for name in ("iterator_temp", "start_temp", "stop_temp", "step_temp"):
+                validate_temp_ref(getattr(value, name), f"{label}.{name}")
+            validate_expr(value.start, f"{label}.start")
+            validate_expr(value.stop, f"{label}.stop")
+            validate_expr(value.step, f"{label}.step")
+            require_tuple(value.body, IRStmt, f"{label}.body")
+            for i, stmt in enumerate(value.body):
+                validate_stmt(stmt, f"{label}.body[{i}]")
+        elif isinstance(value, IRFixedListLoop):
+            validate_symbol_ref(value.collection, f"{label}.collection")
+            validate_symbol_ref(value.value_target, f"{label}.value_target")
+            if value.index_target is not None:
+                validate_symbol_ref(value.index_target, f"{label}.index_target")
+            validate_temp_ref(value.iterator_temp, f"{label}.iterator_temp")
+            if (value.index_start is None) != (value.index_start_temp is None):
+                fail("Typed IR fixed-list loop has inconsistent index-start fields.")
+            if value.index_start is not None:
+                validate_expr(value.index_start, f"{label}.index_start")
+                validate_temp_ref(value.index_start_temp, f"{label}.index_start_temp")
+            require_tuple(value.body, IRStmt, f"{label}.body")
+            for i, stmt in enumerate(value.body):
+                validate_stmt(stmt, f"{label}.body[{i}]")
+        elif isinstance(value, (IRBreak, IRContinue)):
+            if not isinstance(value.target, IRLoopControlTarget):
+                fail("Typed IR loop-control statement has an invalid target.")
+        elif isinstance(value, IRReturn):
+            if value.value is not None:
+                validate_expr(value.value, f"{label}.value")
+        else:
+            fail(f"Unknown typed IR statement node {type(value).__name__}.")
+
+    if not isinstance(module, IRModule):
+        fail("Typed IR validation received a non-IR module.")
+    if not isinstance(module.source_name, str) or not module.source_name:
+        fail("Typed IR module source_name must be non-empty text.")
+    require_tuple(module.storages, IRStorageDecl, "module.storages")
+    require_tuple(module.objects, IRObjectDecl, "module.objects")
+    require_tuple(module.setup, IRStmt, "module.setup")
+    require_tuple(module.main_loop, IRStmt, "module.main_loop")
+    require_tuple(module.functions, IRFunction, "module.functions")
+    require_tuple(module.generated_temporaries, IRTempRef, "module.generated_temporaries")
+
+    for i, decl in enumerate(module.storages):
+        validate_symbol_ref(decl.symbol, f"module.storages[{i}].symbol")
+        if not isinstance(decl.storage, StorageClass):
+            fail("Typed IR storage declaration has an invalid storage class.")
+        if decl.initializer is not None:
+            validate_expr(decl.initializer, f"module.storages[{i}].initializer")
+        require_span(decl.span, f"module.storages[{i}].span")
+
+    for i, obj in enumerate(module.objects):
+        validate_symbol_ref(obj.symbol, f"module.objects[{i}].symbol")
+        if not isinstance(obj.class_name, str) or not obj.class_name:
+            fail("Typed IR object declaration has an invalid class name.")
+        require_tuple(obj.args, IRExpr, f"module.objects[{i}].args")
+        for j, arg in enumerate(obj.args):
+            validate_expr(arg, f"module.objects[{i}].args[{j}]")
+        require_span(obj.span, f"module.objects[{i}].span")
+
+    for i, fn in enumerate(module.functions):
+        validate_function_ref(fn.symbol, f"module.functions[{i}].symbol")
+        require_tuple(fn.parameters, IRSymbolRef, f"module.functions[{i}].parameters")
+        for j, param in enumerate(fn.parameters):
+            validate_symbol_ref(param, f"module.functions[{i}].parameters[{j}]")
+        validate_type(fn.return_type, f"module.functions[{i}].return_type")
+        require_tuple(fn.body, IRStmt, f"module.functions[{i}].body")
+        for j, stmt in enumerate(fn.body):
+            validate_stmt(stmt, f"module.functions[{i}].body[{j}]")
+        require_span(fn.span, f"module.functions[{i}].span")
+
+    for i, stmt in enumerate(module.setup):
+        validate_stmt(stmt, f"module.setup[{i}]")
+    for i, stmt in enumerate(module.main_loop):
+        validate_stmt(stmt, f"module.main_loop[{i}]")
+    for i, temp in enumerate(module.generated_temporaries):
+        validate_temp_ref(temp, f"module.generated_temporaries[{i}]")
+
+    # Raw AST is forbidden anywhere, including inside values not otherwise
+    # reachable through the typed-node checks above.
+    if any(isinstance(item, ast.AST) for item in _walk_values(module)):
+        fail("Typed IR illegally contains a raw Python AST node.")
+
+    declared_symbols = {
+        decl.symbol.symbol_id for decl in module.storages
+    } | {
+        obj.symbol.symbol_id for obj in module.objects
+    } | {
+        fn.symbol.symbol_id for fn in module.functions
+    }
+    for fn in module.functions:
+        declared_symbols.update(p.symbol_id for p in fn.parameters)
+
+    # Function-local symbols are intentionally not all represented as module
+    # storage declarations. Collect every store/loop target as a declaration point.
+    for item in _walk_values(module):
+        if isinstance(item, (IRStore, IRAugStore, IRRangeLoop)):
+            declared_symbols.add(item.target.symbol_id)
+        if isinstance(item, IRIndexStore):
+            declared_symbols.add(item.collection.symbol_id)
+        if isinstance(item, IRFixedListLoop):
+            declared_symbols.add(item.value_target.symbol_id)
+            if item.index_target is not None:
+                declared_symbols.add(item.index_target.symbol_id)
+
+    temp_ids = {temp.temp_id for temp in module.generated_temporaries}
+    if len(temp_ids) != len(module.generated_temporaries):
+        fail("Typed IR contains duplicate generated temporary IDs.")
+    temp_names = {temp.backend_name for temp in module.generated_temporaries}
+    if len(temp_names) != len(module.generated_temporaries):
+        fail("Typed IR contains duplicate generated temporary backend names.")
+
+    # Every repeated symbol ID must describe the same symbol.  Conflicting
+    # metadata could otherwise silently generate C++ using the wrong storage.
+    symbol_refs: dict[SymbolId, IRSymbolRef] = {}
+    for item in _walk_values(module):
+        if isinstance(item, IRSymbolRef):
+            previous = symbol_refs.get(item.symbol_id)
+            if previous is not None and previous != item:
+                fail(f"Typed IR contains conflicting references for symbol {item.symbol_id}.")
+            symbol_refs[item.symbol_id] = item
+            if item.kind not in {SymbolKind.API, SymbolKind.BUILTIN} and item.symbol_id not in declared_symbols:
+                fail(f"Typed IR references undeclared symbol '{item.source_name}' ({item.symbol_id}).")
+        elif isinstance(item, IRFunctionRef) and item.symbol_id not in declared_symbols:
+            fail(f"Typed IR references undeclared function '{item.source_name}' ({item.symbol_id}).")
+        elif isinstance(item, IRTempRef) and item.temp_id not in temp_ids:
+            fail(f"Typed IR references undeclared temporary {item.temp_id}.")
+
+
+def ir_contains_raw_ast(module: IRModule) -> bool:
+    return any(isinstance(item, ast.AST) for item in _walk_values(module))