Documentation

Module Declaration

Every ARIA-IR program is a module. The module is the top-level container for functions and exports.

(module "name"
  (func ...)
  (export ...))

Functions

Functions are declared with func. Parameters, return types, effects, and intent are all declared explicitly.

(func $name
  (param $x i32)
  (param $y i32)
  (result i32)
  (effects pure)
  (intent "Add two integers")
  (return (add.i32 $x $y)))

Type System

ARIA-IR uses explicit, type-suffixed operations. There is no implicit coercion.

Operations carry their type: add.i32, mul.f64, lt.i32, concat.str.

Effect System

Every function declares its effects. The type checker verifies these declarations at compile time.

Intent Annotations

The intent node carries the AI's stated purpose for a function. It is preserved through compilation and available for verification in Layer 4.

(intent "Compute the nth Fibonacci number using recursion")

Intent annotations are not comments. They are first-class nodes in the AST. They travel with the code through the pipeline.

Control Flow

(if (lt.i32 $x 10)
  (then (return $x))
  (else (return (sub.i32 $x 1))))

(loop $label
  (if (ge.i32 $i $n)
    (then (br $label))
    (else
      ;; loop body
      (set $i (add.i32 $i 1)))))

Bindings

;; Immutable (SSA)
(let %result i32 (add.i32 $x $y))

;; Mutable local
(local mut $counter i32 0)
(set $counter (add.i32 $counter 1))

Exports

Functions must be explicitly exported to be visible outside the module. The $main export is the entry point.

(export $main)
(export $fibonacci)

Module Imports

ARIA-IR supports multi-module programs. A module can import symbols from another file using import. Imported symbols are accessed with qualified names.

(import "math.aria")
(call $math.gcd 48 18)

Compile-Time Evaluation

ARIA supports compile-time code generation through a two-pass model. Comptime blocks are compiled via the C backend, executed natively, and their stdout is parsed as ARIA s-expressions and spliced back into the module. Intent verification applies to the post-expansion IR.

comptime

A top-level comptime block contains functions that run at compile time. Their printed output becomes part of the module.

(module "demo"
  (comptime
    (func $main (result i32) (effects io)
      (print "(func $square (param $x i32) (result i32) (effects pure)\n")
      (print "  (return (mul.i32 $x $x)))\n")
      (return 0)))

  (func $main (result i32) (effects io)
    (print "4^2 = %d\n" (call $square 4))
    (return 0)))

The comptime block compiles and executes at compile time. Its output ($square) is spliced into the module before the main compilation pass.

comptime-val

Sugar for computing a single typed value at compile time. Desugars into a full comptime block internally.

(let %answer i32 (comptime-val i32 (mul.i32 6 7)))

Supported types: i32, i64, u32, u64, f32, f64, i8, i16, u8, u16, bool.

Generics via comptime

Comptime functions that take type names as strings and print type-specialized code. This is the generics mechanism. No templates, no special syntax.

(comptime
  (func $gen_max (param $T (ptr i8)) (effects io)
    (print "(func $max_%s (param $a %s) (param $b %s) (result %s) (effects pure)\n" $T $T $T $T)
    (print "  (if (gt.%s $a $b) (then (return $a)) (else (return $b))))\n" $T))

  (func $main (result i32) (effects io)
    (call $gen_max "i32")
    (call $gen_max "f64")
    (return 0)))

Produces $max_i32 and $max_f64 as fully monomorphized functions. Expansion iterates to a fixed point (max 10 passes) to handle comptime that generates more comptime.

Two-pass model

Expression-level comptime is also supported. A (comptime ...) nested inside an expression must produce exactly one form.

C Backend: Effect Attributes

Effect declarations in ARIA-IR are not just documentation. The C backend translates them into GCC/Clang function attributes that enable real compiler optimizations at -O2. This means the effect system does optimization work in the compiled output, not just in the ARIA type checker.

These attributes are GCC and Clang specific. They are ignored by MSVC. The WAT backend preserves effects as ;;effects: comments before each function definition, since WASM has no native effect system.

;; ARIA-IR
(func $add (param $x i32) (param $y i32) (result i32) (effects pure)
  (return (add.i32 $x $y)))

// Generated C
__attribute__((const))
int32_t add(int32_t x, int32_t y) {
    return x + y;
}

Compile-Time Memory Safety

The ariac checker performs static pointer state analysis. Every pointer variable is tracked through four states: alive, freed, null, and owns-allocation. Eight error classes are detected at compile time.

Memory safety analysis is implemented in ariac. The Clojure compiler does not perform pointer state tracking.