Module semir 

Semantic IR for grammar-embedded predicates and actions.

ANTLR grammars embed target-language semantic predicates and actions that a metadata-first runtime cannot execute directly (issue #9). This module defines the small data-driven language those snippets are translated into: heuristic template matching at codegen time, hand-written tables, and (long term) a real Rust target all lower to the same IR, and the runtime evaluates only the IR.

Design constraints, in priority order:

• Prediction-safe: predicates run speculatively inside adaptive prediction, possibly many times on abandoned paths. PExpr therefore has no mutating node — effects exist only in AStmt, which the runtime executes on committed paths (or transactionally for member-state speculation).
• Allocation-free on the hot path: expression storage is a flat arena indexed by ExprId, and text comparisons resolve borrowed &str operands without materializing Strings (see eval_text_cmp).
• Absence is explicit: recognizer queries that can fail (missing lookahead token, absent context child, no rule argument) produce Value::Null, and comparison semantics over Null are fixed here so every producer of IR agrees on them.

Null semantics

• Eq is true iff both sides are present and equal, or both are Null.
• Ne is the negation of Eq.
• Ordering comparisons (Lt, Le, Gt, Ge) with any Null side are false.
• Arithmetic with any Null operand is Null; division/modulo by zero is Null.
• Truthiness: Null is false, Bool(b) is b, Int(i) is i != 0.

These rules are load-bearing: {...}? lookahead-text predicates must fail when the token is absent (Eq(Null, "text") == false), while context-child text guards must pass when the child is absent (Ne(Null, "text") == true). Predicates that are non-restrictive when a value is absent (rule arguments) compose PExpr::IsNull with Or.

Structs

ExprId

Index of an expression node inside a SemIr arena.

HookId

Opaque identifier of an externally implemented hook.

SemIr

Flat expression/statement arena with an interned string pool.

StmtId

Index of a statement node inside a SemIr arena.

StrId

Index of an interned string inside a SemIr arena.

Enums

AStmt

Effectful action statement node.

ArithOp

Arithmetic operator for PExpr::Arith.

CmpOp

Comparison operator for PExpr::Cmp.

PExpr

Pure predicate expression node.

Value

Evaluation result of a non-text expression.

Traits

ActContext

Mutations the action evaluator needs, on top of predicate queries.

PredContext

Recognizer-state queries the predicate evaluator needs.

Functions

eval_pred

Evaluates a predicate expression to its truthiness.

exec_stmt

Executes an action statement against a mutable context.