Grammar

program     ::= expr
expr        ::= symbol | bytes | int | float | string | list
list        ::= "(" {expr} ")"
quote       ::= "'" expr

module      ::= "(" {definition} ")"
definition  ::= "(" expr expr ("def" | "import") ")"

symbol      ::= non-whitespace, non-paren token
bytes       ::= "0x" hex-digits
int         ::= decimal integer literal
float       ::= decimal floating-point literal
string      ::= double-quoted text
comment     ::= ";" to end of line | "#;" expr

Evaluation is postfix: the last symbol in a list drives dispatch.

Operators

Operator names in the machine evaluator.

Arithmetic

Name	Stack effect	Description
+	b a -> sum	Int/Int -> Int, Float/Float -> Float, mixed Int/Float -> Float
-	b a -> diff	Same type rules as +
*	b a -> product	Same type rules as +
/	b a -> quotient	Int/Int uses integer division, Float/Float uses float division
%	b a -> remainder	Int only
sqrt	a -> sqrt	Float only

Bitwise

Name	Stack effect	Description
&	b a -> a & b	Bitwise AND on Bytes
|	b a -> a | b	Bitwise OR on Bytes
^	b a -> a ^ b	Bitwise XOR on Bytes
~	a -> ~a	Bitwise NOT on Bytes

Shifts and rotates

Name	Stack effect	Description
<<	value shifts -> result	Logical left shift on Bytes
>>>	value shifts -> result	Logical right shift on Bytes
>>	value shifts -> result	Arithmetic right shift on Bytes
rol	value shifts -> result	Rotate left on Bytes
ror	value shifts -> result	Rotate right on Bytes

Stack operations

Name	Stack effect	Description
drop	a ->	Discard top of stack
dup	a -> a a	Duplicate top of stack
swap	b a -> a b	Swap top two items
dip	v (expr) -> ... v	Remove v, evaluate expr, push v back

Expression construction

Name	Stack effect	Description
link	head tail -> Link(head, tail)	Build a Link pair
head	link -> head	Extract head (NIL if missing)
tail	link -> tail	Extract tail (NIL if missing)
is_atom	expr -> 1|0	1 if the value is not a Link, else 0
is_eq	b a -> 1|0	Deep structural equality
eval	expr -> evaluated	Re-enter evaluator on the value
quote	a -> (' a)	Wrap a value in a quotation
symbol	a -> symbol|NIL	Convert Bytes, String, Int, or Float to Symbol
str	a -> string|NIL	Convert any atom to String
float	a -> float|NIL	Convert Int, Bytes, String, or Symbol to Float
int	a -> int|NIL	Convert Bytes, String, Symbol, or Float to Int
bytes	a -> bytes|NIL	Convert Int, Float, String, or Symbol to Bytes
ref	hash -> expr|NIL	Resolve a 32-byte hash via content lookup
load	hash -> full_expr|NIL	Deep-resolve a hash recursively

Control flow and definition

Name	Stack effect	Description
fn	argN ... arg1 params body -> result	Bind arguments in a child environment with lexical parentage
lambda	argN ... arg1 params body -> result	Same as fn but with no parent environment
if	cond then else -> result	Evaluate the condition quotation, then select a branch by truthiness
def	name value ->	Bind value under name in env.def_target, write-once per target

Actors

Name	Stack effect	Description
spawn	body name -> name|NIL	Spawn actor thread running body in a child environment
send	target msg ->	Send msg to target's mailbox
receive	target -> msg|NIL	Block until a message arrives

Special form

quote is handled inline in the evaluator loop, not dispatched as an operator. The ' symbol at the head of a list behaves the same way.

Module system

• Module files use .aex by convention. Each file is a parenthesized sequence of definitions.
• Each definition must be a 3-element form: (value name def) or (prefix path import).
• def stores the raw expression under the name with no runtime evaluation at load time.
• import accepts a filesystem path that may be absolute or relative to the importing file's directory.
• Reference imports use (prefix (0x... ref) import) to load from atom storage by content hash.
• Imported symbols are qualified under the given prefix, and intra-module references are rewritten to fully qualified names.
• Circular imports are rejected via an active-stack guard.

CLI flags

Flag	Description
--tui	Launch the interactive TUI
--headless	Run startup actions without TUI
--eval	Enter evaluation mode
--script <path>	Load a module file; entry defaults to main
--expr "<expr>"	Evaluate a postfix expression
--api	Enable the HTTP API server
--api-port <n>	HTTP API port
--api-host <addr>	HTTP API bind address
--node-default-seed <s>	Override the node default seed

Use --eval with at least one of --script or --expr.

Reserved words and naming rules

• All operator names are reserved.
• quote is also reserved as a special form.
• Module keywords def, import, and ref are reserved.
• Names are UTF-8 symbols, optionally dot-qualified, such as math.sum.
• Unbound symbols silently push NIL.
• Integers in source become Expr.Int literals, not Expr.Bytes.
• Line comments start with ; and run to end of line. Block comments use #;.