wasm-gc: specialize Int comparison against an i64 constant to a native compare

When a boxed `$AverInt` is compared against an Int literal that fits i64
(a bound check `n <= 100`, a wall test `head.x < 1`), the comparison now
lowers to a tag-branch instead of allocating the constant as an `$AverInt`
and calling the general `__aint_cmp`:

  - read `$magf`; if null (Small) load `$small` and do the native signed
    i64 compare against the constant;
  - if non-null (Big) the result is fixed by `$sign` alone — a Big is
    |·| > i64::MAX, so above every i64 constant when positive and below
    every i64 constant when negative; equality against an i64 constant is
    always false.

Both operand orders are handled by flipping the relation (`K < x` ≡
`x > K`). The carrier invariant makes this sound: `__aint_normalize` /
`__aint_from_i64` keep every value in `[i64::MIN, i64::MAX]` as a Small
(it demotes exactly -2^63 to Small) and everything outside as a Big, so
the Small branch is exact and the Big branch is sign-determined.

Fail-closed: a `$AverInt`-vs-`$AverInt` comparison (no literal operand)
stays on `__aint_cmp` byte-for-byte. The non-literal operand is stashed
in a dedicated `(ref null $AverInt)` scratch slot (reserved whenever
bignum is active) so neither field read re-evaluates the operand
expression.

An exhaustive VM-vs-wasm-gc differential is the soundness oracle: every
one of the six comparisons, both operand orders, and constants
{0, 1, -1, 100, -100, i64::MAX, i64::MIN+1} against Small-at-boundary,
Small-far, Big-positive (`a*a*a`) and Big-negative (`0 - a*a*a`) operands
must decode to the same boolean the VM produces. The bound-check program
whose only comparison is against a constant DCEs `__aint_cmp` +
`__aint_decompose` under `--optimize size` (~330 B drop vs the
non-literal-bound twin).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jasisz

src/codegen/wasm_gc/body/from_mir/builtins.rs

@@ -1806,6 +1806,50 @@ pub(crate) fn emit_mir_numeric_binop(
     } else {
         l_ty
     };
+    // bignum const-compare specialization — an `$AverInt` compared
+    // against an i64-fitting Int LITERAL lowers to a tag-branch (Small
+    // → native i64 compare; Big → sign-determined) instead of
+    // allocating the constant as an `$AverInt` and calling
+    // `__aint_cmp`. Fail-closed: only fires when both operands are the
+    // `$AverInt` ref type, exactly one is a literal that `fits_i64`,
+    // and the op is one of the six comparisons. A `$AverInt`-vs-
+    // `$AverInt` comparison (`p.x == q.x`) is NOT a literal on either
+    // side, so it stays on `__aint_cmp` byte-for-byte.
+    if ctx.registry.bignum
+        && ctx.registry.aint_struct_idx.is_some()
+        && operand != Some(ValType::F64)
+        && operand != Some(ValType::I32)
+        && l_ty
+            == ctx
+                .registry
+                .aint_struct_idx
+                .map(crate::codegen::wasm_gc::types::struct_ref)
+        && r_ty
+            == ctx
+                .registry
+                .aint_struct_idx
+                .map(crate::codegen::wasm_gc::types::struct_ref)
+        && matches!(
+            bop.op,
+            BinOp::Eq | BinOp::Neq | BinOp::Lt | BinOp::Gt | BinOp::Lte | BinOp::Gte
+        )
+    {
+        // `const_on_left` records which side the constant sat on so
+        // the tag-branch can flip the comparison (`K < x` ≡ `x > K`).
+        let lit = mir_int_literal(l)
+            .map(|k| (k, true))
+            .or_else(|| mir_int_literal(r).map(|k| (k, false)));
+        if let Some((k, const_on_left)) = lit {
+            // The non-literal operand (the `$AverInt` ref) goes on the
+            // stack; the literal is folded into the branch as an
+            // `i64.const`.
+            let non_lit = if const_on_left { r } else { l };
+            if emit_mir_expr(func, non_lit, slots, ctx)?.is_none() {
+                return Ok(None);
+            }
+            return emit_aint_cmp_const(func, bop.op, k, const_on_left, slots, ctx);
+        }
+    }
     if emit_mir_expr(func, l, slots, ctx)?.is_none() {
         return Ok(None);
     }
@@ -1934,3 +1978,146 @@ fn emit_aint_binop(
     }
     Ok(Some(()))
 }
+
+/// If `expr` is a literal `Int`, return its `i64` value. Used by the
+/// const-compare specialization to peel the constant operand of an
+/// `$AverInt`-vs-constant comparison. `Literal::Int` is an `i64` in the
+/// AST, so the value is always `fits_i64` by construction — there is no
+/// out-of-range Int literal to reject. (A source literal that exceeds
+/// `i64` is rejected at lex/parse time, before MIR.)
+fn mir_int_literal(expr: &Spanned<MirExpr>) -> Option<i64> {
+    match &expr.node {
+        MirExpr::Literal(l) => match l.node {
+            crate::ast::Literal::Int(n) => Some(n),
+            _ => None,
+        },
+        _ => None,
+    }
+}
+
+/// bignum const-compare specialization — the non-literal `$AverInt`
+/// operand is already on the stack; emit a tag-branch comparison
+/// against the i64 constant `k` and leave an i32 bool, replacing the
+/// general `__aint_cmp` call.
+///
+/// Soundness rests on the carrier invariant (`__aint_normalize` /
+/// `__aint_from_i64`): a value is **Small** (`$magf == null`) iff it is
+/// in `[i64::MIN, i64::MAX]` — the FULL i64 range, including `i64::MIN`
+/// which `normalize` deliberately demotes to a Small. A value is
+/// **Big** (`$magf != null`) iff `|value| > i64::MAX`, i.e. strictly
+/// outside the i64 range, with `$sign ∈ {-1, +1}`. Therefore:
+///   - Small → load `$small` and do the NATIVE signed i64 compare
+///     against `k`.
+///   - Big → the relation against any i64 constant is fixed by `$sign`
+///     alone: a Big-positive is `> k` for every i64 `k`, a Big-negative
+///     is `< k`; and a Big NEVER equals an i64 constant.
+///
+/// `const_on_left` flips the comparison so the `$AverInt` is always the
+/// left operand of the EFFECTIVE relation (`k < x` ≡ `x > k`).
+fn emit_aint_cmp_const(
+    func: &mut Function,
+    op: BinOp,
+    k: i64,
+    const_on_left: bool,
+    slots: &SlotTable,
+    ctx: &EmitCtx<'_>,
+) -> Result<Option<()>, WasmGcError> {
+    let aint_idx = ctx.registry.aint_struct_idx.ok_or(WasmGcError::Validation(
+        "const-compare specialization requires the $AverInt struct slot".into(),
+    ))?;
+    let scratch = slots.const_cmp_scratch.ok_or(WasmGcError::Validation(
+        "const-compare specialization needs a scratch slot but none was reserved".into(),
+    ))?;
+
+    // Normalize so the `$AverInt` is the LEFT operand of the effective
+    // relation. The source spelled `const OP aint` when `const_on_left`,
+    // which is equivalent to `aint OP_flipped const`.
+    let eff = if const_on_left { flip_cmp(op) } else { op };
+
+    // Stash the operand so both field reads (`$magf`, then `$small` /
+    // `$sign`) read the same value without re-emitting the operand
+    // expression.
+    func.instruction(&Instruction::LocalSet(scratch));
+
+    let block_ty = wasm_encoder::BlockType::Result(ValType::I32);
+    // if ($magf == null) → Small
+    func.instruction(&Instruction::LocalGet(scratch));
+    func.instruction(&Instruction::StructGet {
+        struct_type_index: aint_idx,
+        field_index: 1,
+    });
+    func.instruction(&Instruction::RefIsNull);
+    func.instruction(&Instruction::If(block_ty));
+
+    // ── Small: native i64 compare of `$small` against `k` ──
+    func.instruction(&Instruction::LocalGet(scratch));
+    func.instruction(&Instruction::StructGet {
+        struct_type_index: aint_idx,
+        field_index: 0,
+    });
+    func.instruction(&Instruction::I64Const(k));
+    func.instruction(&match eff {
+        BinOp::Eq => Instruction::I64Eq,
+        BinOp::Neq => Instruction::I64Ne,
+        BinOp::Lt => Instruction::I64LtS,
+        BinOp::Gt => Instruction::I64GtS,
+        BinOp::Lte => Instruction::I64LeS,
+        BinOp::Gte => Instruction::I64GeS,
+        _ => unreachable!("emit_aint_cmp_const gated to the six comparisons"),
+    });
+
+    func.instruction(&Instruction::Else);
+
+    // ── Big: the result is determined by `$sign` alone ──
+    // A Big-positive (`$sign > 0`) exceeds every i64 `k`; a Big-negative
+    // (`$sign < 0`) is below every i64 `k`; a Big never equals `k`.
+    match eff {
+        // x < k  ⟺  x is Big-negative  ⟺  $sign < 0
+        // x <= k ⟺  same (Big never == k)
+        BinOp::Lt | BinOp::Lte => {
+            func.instruction(&Instruction::LocalGet(scratch));
+            func.instruction(&Instruction::StructGet {
+                struct_type_index: aint_idx,
+                field_index: 2,
+            });
+            func.instruction(&Instruction::I32Const(0));
+            func.instruction(&Instruction::I32LtS);
+        }
+        // x > k  ⟺  x is Big-positive  ⟺  $sign > 0
+        // x >= k ⟺  same (Big never == k)
+        BinOp::Gt | BinOp::Gte => {
+            func.instruction(&Instruction::LocalGet(scratch));
+            func.instruction(&Instruction::StructGet {
+                struct_type_index: aint_idx,
+                field_index: 2,
+            });
+            func.instruction(&Instruction::I32Const(0));
+            func.instruction(&Instruction::I32GtS);
+        }
+        // A Big never equals an i64 constant.
+        BinOp::Eq => {
+            func.instruction(&Instruction::I32Const(0));
+        }
+        BinOp::Neq => {
+            func.instruction(&Instruction::I32Const(1));
+        }
+        _ => unreachable!("emit_aint_cmp_const gated to the six comparisons"),
+    }
+
+    func.instruction(&Instruction::End);
+    Ok(Some(()))
+}
+
+/// Flip a comparison operator across its operands: `k OP x` ≡
+/// `x flip(OP) k`. Equality / inequality are symmetric and unchanged.
+fn flip_cmp(op: BinOp) -> BinOp {
+    match op {
+        BinOp::Lt => BinOp::Gt,
+        BinOp::Gt => BinOp::Lt,
+        BinOp::Lte => BinOp::Gte,
+        BinOp::Gte => BinOp::Lte,
+        BinOp::Eq => BinOp::Eq,
+        BinOp::Neq => BinOp::Neq,
+        other => other,
+    }
+}

src/codegen/wasm_gc/body/slots.rs

@@ -18,7 +18,7 @@ use crate::ir::hir::{
 use crate::types::Type;
 
 use super::super::WasmGcError;
-use super::super::types::{TypeRegistry, aver_to_wasm};
+use super::super::types::{TypeRegistry, aver_to_wasm, struct_ref};
 use super::FnMap;
 use super::infer::{
     arm_is_option_pattern_resolved, arm_is_result_pattern_resolved, aver_type_str_of,
@@ -93,6 +93,18 @@ pub(super) struct SlotTable {
     /// `Random.int(readBound(), 10)`). Stash `min` once after first
     /// emit and reuse via LocalGet.
     pub(super) random_int_wasip2_min_scratch: Option<u32>,
+    /// Scratch `(ref null $AverInt)` slot for the const-compare
+    /// specialization (`$AverInt` compared against an i64-fitting
+    /// literal). The non-literal operand is stashed here once so the
+    /// tag-branch can read its `$magf` (Small/Big discriminant) and
+    /// then its `$small`/`$sign` field without re-emitting the operand
+    /// expression — which would double-run any side effect in it.
+    /// Reserved whenever `bignum` is active (one unused ref local when
+    /// no const-comparison is present — cheaper than walking the MIR
+    /// body here, which would couple slot allocation to the body walk
+    /// and break the differential-gate invariant that `build_for_fn`
+    /// reads only the resolver tables, not the MIR body).
+    pub(super) const_cmp_scratch: Option<u32>,
 }
 
 impl SlotTable {
@@ -298,6 +310,23 @@ impl SlotTable {
         } else {
             None
         };
+        // Const-compare specialization scratch: a single `(ref null
+        // $AverInt)` slot to stash the non-literal operand of an
+        // `$AverInt`-vs-i64-constant comparison. Reserved whenever
+        // bignum is active so the slot index is a pure function of the
+        // registry flag (not the MIR body), preserving the invariant
+        // that `build_for_fn` keys only off the resolver tables.
+        let const_cmp_scratch = if registry.bignum {
+            if let Some(aint_idx) = registry.aint_struct_idx {
+                let idx = by_slot.len() as u32;
+                by_slot.push(struct_ref(aint_idx));
+                Some(idx)
+            } else {
+                None
+            }
+        } else {
+            None
+        };
         Ok(Self {
             by_slot,
             subject_scratch,
@@ -307,6 +336,7 @@ impl SlotTable {
             args_get_wasip2_retptr_scratch,
             env_get_wasip2_scratch,
             random_int_wasip2_min_scratch,
+            const_cmp_scratch,
         })
     }