Envzn Intermediate Representation (EvIR) — Specification and Lowering

Generated — do not edit by hand. This document is produced by a generator from the compiler's own spec-trace, which it emits as it traces every construct. Regenerate after any trace change; the companion ENVZN_CONSTITUTION.md (Article II) summarises it and must stay in sync.

Envzn compiles through its own intermediate representation, the EvIR. The front end tokenizes and parses source into an AST and analyzes it; the analyzed tree is then built into EvIR nodes (build_ir), and the EvIR is lowered to C++20 (compiler/evir/emitter.py), which clang++ turns into a native executable. Section A specifies the EvIR node set in fourteen logical groups; Section B records how each node lowers to C++, covering all 531 traced mappings.

Section A — The EvIR

The node set of the Envzn intermediate representation, grouped by role. Every concrete node defined in compiler/evir/nodes.py appears in exactly one group; the abstract roots IrExpr and IrStmt are category framing, not elements.

Part A.i — Literals and constants

The leaf value nodes — the constants a program writes directly. Each carries its resolved type and lowers to the corresponding C++ literal or kernel value; the absence leaves (EMPTY, none) carry no payload and stand for an unoccupied class or pipe slot.

• IrIntLit — an integer literal, typed by the analyzer (the context-free default is int64)
• IrBinaryLit — a literal WRITTEN as a bit pattern (0xC3, 0b1100); a subclass of IrIntLit by value, typed binary for an octet and by written width beyond it — the node, not a field, says it is a bit pattern (I.D(b))
• IrFloatLit — a floating-point literal (default float64)
• IrBoolLit — a boolean literal — TRUE or FALSE
• IrCharLit — a char32 code-point literal
• IrStringLit — an interned immutable String literal
• IrArrayLit — an array literal, [a, b, c]
• IrStatusLit — a STATUS literal — SUCCESS, PARTIAL_SUCCESS, or FAILURE(message, code)
• IrEmpty — the EMPTY absence value of a class-typed slot
• IrNone — the none value of an unoccupied pipe / optional slot

Part A.ii — References and access paths

The nodes that name an existing value rather than compute a new one — reads of locals, the receiver, data fields, and indexed elements. Each resolves to a place the surrounding node reads from or writes to, and the access form (owning handle, borrow, value-array slot) decides how it lowers.

• IrVarRef — a read of a local, parameter, or constant
• IrSelf — the receiver SELF inside a method
• IrFieldRead — a data-field read through . (owning, reference, or chain receiver)
• IrIndex — an indexed access coll[i] over an array, value-array, or collection
• IrMultiIndex — a dense N-D subscript a[i, j, …] — fused column-major access on the EvNdArray companion; the element may be an OBJECT, whose cell is an owning handle

Part A.iii — Operators and conversions

Computation over values: the arithmetic, comparison, bitwise, and logical operators, and the explicit AS / INTO conversions together with the CONVERSIONS hosts that define them. Conversions are always explicit and checked; there is no implicit cast.

• IrBinary — a binary operator — arithmetic, comparison, bitwise, shift, or BEQUALS
• IrUnary — a unary operator — negate, NOT, BNOT, factorial, increment/decrement
• IrConvert — an AS / INTO conversion at a use site
• IrPrimCast — a primitive numeric cast (static_cast<T>) — the int/float-arm coercion behind number construction and widening
• IrCoerce — an IMPLICIT scalar conversion the analyzer admitted, stated on the IR (Phase 4d.1) — kind (compiler.coercion.CoerceKind) names WHICH clause (widen, reinterpret, a provably-safe narrow, an octet range check or offset shim, a folded constant) admitted the crossing with no explicit AS/INTO
• IrDuplicate — a DUPLICATE value deep copy. The value-vs-reference SHAPE decision is made in build_ir, not the emitter: a BORROW operand (a =@ REFERENCE local, a handle-ABI borrow param, or the IrElementRef transition build_ir inserts for a DUPLICATE arr[i] storage cell) lowers to ENVZN::_ev_duplicate_ref<T>(operand); every other operand (owning handle / value / primitive) binds the by-value ENVZN::_ev_duplicate(value) (owning handle deep-clones, value/primitive value-copies).
• IrConversions — a CONVERSIONS host declaring the AS/INTO operators for a type
• IrConversionOp — a single AS or INTO operator definition
• IrOpaqueOp — an opaque[T]->wrap / ->unwrap static-dispatch operation
• IrGetPointee — a representation-shape bridge: OWNING → BORROW, lowering inner.get()
• IrAddressOf — a representation-shape bridge: VALUE_REF → BORROW, lowering &inner
• IrDeref — a representation-shape bridge: BORROW → VALUE, lowering (*inner)
• IrElementRef — a representation-shape bridge: a storage-array cell → BORROW referent pointer, lowering _ev_ref_of(recv.data()[index]). The mutable subscript yields a non-copyable _Ref write proxy, so the element is reached through .data()[index]; _ev_ref_of splits shape (&elem value / .get() referent owning). build_ir inserts it for DUPLICATE arr[i] (the inline form of REFERENCE r =@ arr[i]; DUPLICATE r).
• IrRefOf — a reference-source bridge: a value → BORROW referent pointer via _ev_ref_of(inner). The =@ bind of a generic TYPE_PARAM source (resolves per-instantiation — .get() for a class T, & for a primitive T) and the general reference-source fallback.
• IrPipeSlotRef — a reference-source bridge: an Array[T] wrapper subscript success-slot → BORROW pointer via _EvGet<0>(inner). The wrapper arr[i] yields the pipe-XOR (REFERENCE T | STATUS) tuple; =@ binds the success-slot reference pointer directly.
• IrMutRefCast — a reference-source bridge: a VALUE_REF (const T& value-reference) → BORROW pointer, const-stripped so a MUTABLE REFERENCE T* field slot also accepts it, via const_cast<...>(&inner).
• IrWeakLock — the FALLIBLE deref of a WEAK REFERENCE handle: weak handle → (REFERENCE T | EMPTY), lowering to _ev_weak<T>::lock() plus a validity test (C++) or an is_alive load and branch on the referent preamble (LLVM). RESERVED, PENDING IMPLEMENTATION (2026-09-14) — not yet constructed and WEAK REFERENCE has no token, but it has a committed consumer in the nullable foreign key of ORMapping; the node exists so the lock operation has an IR anchor rather than being re-derived in the emitter from MatchSubject.WEAK.

Part A.iv — Calls, construction, and lambdas

The nodes that invoke behaviour or build instances — resolved method and static calls, heap construction through INIT and SUPER, and lambdas. Overload resolution is settled before lowering, so each call node already names its concrete target.

• IrCall — a method or namespace/static call, overload resolved by argument types
• IrCreate — a heap-class CREATE — allocation reached through an owning handle
• IrNdAlloc — an implicit dense N-D construction float64[m,n] / float64[3,4] — ENVZN::EvNdArray<elem, RANK>(dims…), a selector resolving to _NdArray (blittable) or _NdObjectArray (object)
• IrNdWiden — a fixed→spine N-D widening — a compile-time fixed-shape array (EvNdArrayFixed) materialized as a runtime spine EvNdArray<elem, RANK> when it flows into a float64[,] binding; total, one-directional
• IrInit — an INIT constructor — its initializer list and body
• IrSuperInit — a SUPER(...) base-constructor call, emitted in the initializer list (sub-node)
• IrLambda — a lambda — expression form, block form, or no-parameter task body

Part A.v — Bindings and assignment

The nodes that introduce or update storage. The binding operator carried by each one — copy, move, or non-owning reference — is part of its meaning and decides whether the right-hand value is copied, moved, or borrowed as it lowers.

• IrLet — a local declaration with its binding operator (=, :=, =@)
• IrAssign — an assignment to an existing local, field, or reference
• IrMultiAssign — a multi-value assignment from a comma- or pipe-shaped return
• IrIndexAssign — an indexed write coll[i] = v (move or clone, per form)

Part A.vi — Control flow

The structured-control nodes — blocks, conditionals, loops, MATCH, and compile-time type narrowing — together with the clause and arm components they are built from. Control flow is always reducible; there is no arbitrary jump.

• IrBlock — a brace-delimited statement sequence and its scope
• IrIf — a conditional with its then / else-if / else clauses
• IrClause — a single condition-and-body clause within an IF or WHEN chain (sub-node)
• IrLoop — a loop — counted FOR, range FOR IN, WHILE, or LOOP
• IrNdForEach — a dense N-D coordinate walk FOR (i, j) IN grid — nested loops, contiguous axis innermost
• IrBreak — a BREAK out of the enclosing loop
• IrContinue — a CONTINUE to the next iteration
• IrMatch — a MATCH over a class, STATUS, or enum with exhaustive arms
• IrMatchArm — a single WHEN arm of a MATCH, with its binding (sub-node)
• IrWhenImplements — a compile-time WHEN ... IMPLEMENTS type-narrowing block

Part A.vii — Returns and expression statements

How a method hands values back and how an expression runs for its effect. The return nodes carry the single-, comma-, and pipe-XOR-shaped results, applying any required clone or move as the value leaves the callee.

• IrReturn — a RETURN, applying any required clone or move to the value as it leaves
• IrMultiReturn — a return populating several slots (comma or pipe-XOR shape)
• IrMultiSlot — a single named slot within a multi-value return (sub-node)
• IrExprStmt — an expression evaluated for its effect as a statement

Part A.viii — Recoverable failure and presence

The STATUS / pipe-XOR machinery and the presence tests. These nodes express the language's recoverable-failure vocabulary — consuming a pipe-XOR call in an IF or WHILE, reading its success or failure slots, and testing STATUS or class-value presence — kept strictly apart from the unrecoverable path.

• IrPipeIf — an IF whose condition is a fallible pipe-XOR producer (a pipe-returning call, a fallible AS/INTO, a SETS_ERRNO FOREIGN call, or a collection/__op_index__ mirror subscript), narrowing $= / $! in its branches. A bare value-array T[]/T[N]/T[N+] subscript is NOT a producer — it is a direct bounds-checked read — so IF arr[i] THEN over a value array is an ordinary boolean IrIf, not this node
• IrPipeWhile — a WHILE driven by a pipe-XOR call
• IrPipeRead — a read of a pipe result slot — $=, $=[i], $!, $#
• IrIsStatus — an IS SUCCESS / IS FAILURE / IS PARTIAL_SUCCESS test
• IrIsValid — an IS VALID / IS NOT VALID presence test on a class value

Part A.ix — Unrecoverable failure and assertions

The PANIC / RECOVER path for unrecoverable error, and the ASSERT family for programmer-error checks that halt. Distinct from the recoverable STATUS vocabulary of the previous group: these unwind or abort rather than return a value.

• IrPanic — a PANIC of an Error subclass
• IrTry — a TRY with its RECOVER and FINALLY clauses
• IrRecover — a single RECOVER clause binding a caught Error type (sub-node)
• IrAssert — an ASSERT / ASSERT! programmer-error check (halts on failure)
• IrUnreachable — an UNREACHABLE! always-on unconditional halt — diverging (satisfies definite-return)

Part A.x — Concurrency

The structured-concurrency nodes: the CONCURRENT scope that joins before it unwinds, the PARALLEL task launched within it, and the SYNCHRONIZED critical section. Each lowers onto the C++ threading runtime with its lifetime guarantees intact.

• IrConcurrent — a CONCURRENT structured-scope block (RAII join-before-unwind)
• IrParallel — a PARALLEL task launch within a CONCURRENT scope
• IrSynchronized — a SYNCHRONIZED(lock) critical section

Part A.xi — Program structure

The declaration nodes that give a module its shape — classes, namespaces, interfaces, structs, groups, enums — and the members within them: methods, signatures, parameters, and fields. These are the top-level nodes a module is a sequence of.

• IrClass — a CLASS declaration — fields, methods, layout, and destructor
• IrNamespace — a NAMESPACE — a stateless host of free functions plus CONSTANT data; lowers to a C++ namespace
• IrInterface — an INTERFACE declaration — pure-virtual method signatures
• IrStruct — a STRUCT — a public-field data record with generated construction
• IrUnion — a kernel-internal UNION raw-storage block (one typed arm live, no discriminant) lowering to a C++ union — backs the number value-class
• IrGroup — a GROUP — a tagged set of named constants
• IrEnum — an ENUM declaration and its cases
• IrMethod — a method definition — signature, body, MODIFY/const, OVERRIDE
• IrMethodSig — a method signature without a body (interface or abstract) (sub-node)
• IrParam — a parameter — plain, REFERENCE, MUTABLE REFERENCE, MOVE, or variadic
• IrField — a data field — owning, REFERENCE, SHARED MUTABLE REFERENCE, or CONSTANT

Part A.xii — Foreign and unsafe

The typed foreign-function boundary and the UNSAFE gate around raw-handle access. The FOREIGN and BIND nodes reach genuine C symbols with their types stated; UNSAFE marks the only scope in which a raw foreign handle may be read.

• IrForeignExpr — an inline FOREIGN expression block
• IrForeignStmt — an inline FOREIGN statement block
• IrForeignBind — a FOREIGN BIND to a C function — a typed FFI call
• IrForeignConstant — a FOREIGN BIND to a C constant
• IrForeignTypeBind — a FOREIGN_TYPE BIND to a C struct or opaque handle
• IrUnsafe — an UNSAFE { } block gating raw-handle access

Part A.xiii — Debug instrumentation

The debug-only capture nodes. They are present in the IR under a debug build and elided otherwise, and never change the meaning of the program they observe.

• IrSnapshot — a SNAPSHOT debug capture of a value
• IrStacktrace — a STACKTRACE debug statement
• IrBinding — one in-scope name (scope-capture unit consumed by IrSnapshot) (sub-node)

Part A.xiv — Types and lifetime

The type representation every node carries, and the scope-exit destruction markers that drive deterministic cleanup. ResolvedType is the resolved type a node was given by the analyzer; IrDrop records where an owned value's life ends on the NORMAL path, and IrCleanupPad records the same for the EXCEPTIONAL one.

• ResolvedType — the resolved type a node carries — primitive, class handle, value-array, or collection
• IrDrop — a scope-exit destruction marker (RAII; the C++ destructor emits it implicitly) (sub-node)
• IrCleanupPad — the drops an EXCEPTION passing through a point must run — one row per DISTINCT live set (deduplicated, so the count matches a landing-pad count rather than a call count), innermost-first in reverse declaration order. Carried as a method-level table (cleanup_pads on IrMethod/IrInit/IrClass) plus a per-statement pad_id stamp, because the live set changes at every declaration rather than per lexical scope and an IF arm is a bare statement tuple with no node to hang a field on. RESERVED, INERT (2026-09-14) — no producer; drop_insertion will supply it as a fifth caller of the _frames_to_unwind computation that already answers this for four other exit kinds, and cxx_emit clears it beside the drops it already strips, so golden does not move. (sub-node)

Section B — Lowering EvIR to C++

How each EvIR node lowers to C++20, organised by the same fourteen groups. Each row is one traced mapping from that spec-trace: the node, the variant or concept that distinguishes it, the C++ shape it emits, and the governing constitution reference. Structural sub-nodes (clauses, arms, slots) carry no standalone lowering and are noted inline under their parent group.

Part B.i — Literals and constants

IrIntLit — an integer literal, typed by the analyzer (the context-free default is int64)

IrFloatLit — a floating-point literal (default float64)

IrBoolLit — a boolean literal — TRUE or FALSE

IrCharLit — a char32 code-point literal

IrStringLit — an interned immutable String literal

IrArrayLit — an array literal, [a, b, c]

IrStatusLit — a STATUS literal — SUCCESS, PARTIAL_SUCCESS, or FAILURE(message, code)

IrEmpty — the EMPTY absence value of a class-typed slot

IrNone — the none value of an unoccupied pipe / optional slot

Defined in the IR, lowering not yet spec-traced (node present in compiler/evir/nodes.py; see compiler/evir/emitter.py for current emission): IrBinaryLit.

Part B.ii — References and access paths

IrVarRef — a read of a local, parameter, or constant

IrSelf — the receiver SELF inside a method

IrFieldRead — a data-field read through . (owning, reference, or chain receiver)

IrIndex — an indexed access coll[i] over an array, value-array, or collection

IrMultiIndex — a dense N-D subscript a[i, j, …] — fused column-major access on the EvNdArray companion; the element may be an OBJECT, whose cell is an owning handle

Part B.iii — Operators and conversions

IrBinary — a binary operator — arithmetic, comparison, bitwise, shift, or BEQUALS

IrUnary — a unary operator — negate, NOT, BNOT, factorial, increment/decrement

IrConvert — an AS / INTO conversion at a use site

IrPrimCast — a primitive numeric cast (static_cast<T>) — the int/float-arm coercion behind number construction and widening

IrCoerce — an IMPLICIT scalar conversion the analyzer admitted, stated on the IR (Phase 4d.1) — kind (compiler.coercion.CoerceKind) names WHICH clause (widen, reinterpret, a provably-safe narrow, an octet range check or offset shim, a folded constant) admitted the crossing with no explicit AS/INTO

IrConversions — a CONVERSIONS host declaring the AS/INTO operators for a type

IrConversionOp — a single AS or INTO operator definition

IrOpaqueOp — an opaque[T]->wrap / ->unwrap static-dispatch operation

Defined in the IR, lowering not yet spec-traced (node present in compiler/evir/nodes.py; see compiler/evir/emitter.py for current emission): IrDuplicate, IrGetPointee, IrAddressOf, IrDeref, IrElementRef, IrRefOf, IrPipeSlotRef, IrMutRefCast, IrWeakLock.

Part B.iv — Calls, construction, and lambdas

IrCall — a method or namespace/static call, overload resolved by argument types

IrCreate — a heap-class CREATE — allocation reached through an owning handle

IrNdAlloc — an implicit dense N-D construction float64[m,n] / float64[3,4] — ENVZN::EvNdArray<elem, RANK>(dims…), a selector resolving to _NdArray (blittable) or _NdObjectArray (object)

IrNdWiden — a fixed→spine N-D widening — a compile-time fixed-shape array (EvNdArrayFixed) materialized as a runtime spine EvNdArray<elem, RANK> when it flows into a float64[,] binding; total, one-directional

IrInit — an INIT constructor — its initializer list and body

IrLambda — a lambda — expression form, block form, or no-parameter task body

Sub-nodes (structural components, lowered as part of their parent — no standalone form): IrSuperInit — a SUPER(...) call, emitted in the IrInit initializer list.

Part B.v — Bindings and assignment

IrLet — a local declaration with its binding operator (=, :=, =@)

IrAssign — an assignment to an existing local, field, or reference

IrMultiAssign — a multi-value assignment from a comma- or pipe-shaped return

IrIndexAssign — an indexed write coll[i] = v (move or clone, per form)

Part B.vi — Control flow

IrBlock — a brace-delimited statement sequence and its scope

IrIf — a conditional with its then / else-if / else clauses

IrLoop — a loop — counted FOR, range FOR IN, WHILE, or LOOP

IrNdForEach — a dense N-D coordinate walk FOR (i, j) IN grid — nested loops, contiguous axis innermost

IrBreak — a BREAK out of the enclosing loop

IrContinue — a CONTINUE to the next iteration

IrMatch — a MATCH over a class, STATUS, or enum with exhaustive arms

IrWhenImplements — a compile-time WHEN ... IMPLEMENTS type-narrowing block

Sub-nodes (structural components, lowered as part of their parent — no standalone form): IrClause — a condition-and-body clause, lowered within its IrIf / IrWhenImplements; IrMatchArm — a WHEN arm, lowered within its IrMatch.

Part B.vii — Returns and expression statements

IrReturn — a RETURN, applying any required clone or move to the value as it leaves

IrMultiReturn — a return populating several slots (comma or pipe-XOR shape)

IrExprStmt — an expression evaluated for its effect as a statement

Sub-nodes (structural components, lowered as part of their parent — no standalone form): IrMultiSlot — a return slot, lowered within its IrMultiReturn tuple.

Part B.viii — Recoverable failure and presence

IrPipeIf — an IF whose condition is a fallible pipe-XOR producer (a pipe-returning call, a fallible AS/INTO, a SETS_ERRNO FOREIGN call, or a collection/__op_index__ mirror subscript), narrowing $= / $! in its branches. A bare value-array T[]/T[N]/T[N+] subscript is NOT a producer — it is a direct bounds-checked read — so IF arr[i] THEN over a value array is an ordinary boolean IrIf, not this node

IrPipeWhile — a WHILE driven by a pipe-XOR call

IrPipeRead — a read of a pipe result slot — $=, $=[i], $!, $#

IrIsStatus — an IS SUCCESS / IS FAILURE / IS PARTIAL_SUCCESS test

IrIsValid — an IS VALID / IS NOT VALID presence test on a class value

Part B.ix — Unrecoverable failure and assertions

IrPanic — a PANIC of an Error subclass

IrTry — a TRY with its RECOVER and FINALLY clauses

IrAssert — an ASSERT / ASSERT! programmer-error check (halts on failure)

Sub-nodes (structural components, lowered as part of their parent — no standalone form): IrRecover — a RECOVER clause, lowered within its IrTry.

Defined in the IR, lowering not yet spec-traced (node present in compiler/evir/nodes.py; see compiler/evir/emitter.py for current emission): IrUnreachable.

Part B.x — Concurrency

IrConcurrent — a CONCURRENT structured-scope block (RAII join-before-unwind)

IrParallel — a PARALLEL task launch within a CONCURRENT scope

IrSynchronized — a SYNCHRONIZED(lock) critical section

Part B.xi — Program structure

IrClass — a CLASS declaration — fields, methods, layout, and destructor

IrNamespace — a NAMESPACE — a stateless host of free functions plus CONSTANT data; lowers to a C++ namespace

IrInterface — an INTERFACE declaration — pure-virtual method signatures

IrStruct — a STRUCT — a public-field data record with generated construction

IrGroup — a GROUP — a tagged set of named constants

IrEnum — an ENUM declaration and its cases

IrMethod — a method definition — signature, body, MODIFY/const, OVERRIDE

IrParam — a parameter — plain, REFERENCE, MUTABLE REFERENCE, MOVE, or variadic

IrField — a data field — owning, REFERENCE, SHARED MUTABLE REFERENCE, or CONSTANT

Sub-nodes (structural components, lowered as part of their parent — no standalone form): IrMethodSig — a pure-virtual signature, lowered within its IrInterface.

Defined in the IR, lowering not yet spec-traced (node present in compiler/evir/nodes.py; see compiler/evir/emitter.py for current emission): IrUnion.

Part B.xii — Foreign and unsafe

IrForeignExpr — an inline FOREIGN expression block

IrForeignStmt — an inline FOREIGN statement block

IrForeignBind — a FOREIGN BIND to a C function — a typed FFI call

IrForeignConstant — a FOREIGN BIND to a C constant

IrForeignTypeBind — a FOREIGN_TYPE BIND to a C struct or opaque handle

IrUnsafe — an UNSAFE { } block gating raw-handle access

Part B.xiii — Debug instrumentation

IrSnapshot — a SNAPSHOT debug capture of a value

IrStacktrace — a STACKTRACE debug statement

Defined in the IR, lowering not yet spec-traced (node present in compiler/evir/nodes.py; see compiler/evir/emitter.py for current emission): IrBinding.

Part B.xiv — Types and lifetime

ResolvedType — the resolved type a node carries — primitive, class handle, value-array, or collection

Sub-nodes (structural components, lowered as part of their parent — no standalone form): IrDrop — a scope-exit drop, emitted implicitly by the C++ destructor (RAII); IrCleanupPad — an unwind-path drop set, cleared before emit alongside IrDrop.

Section C — The lowering model and implementation notes

Curated narrative — not generated from the TSV. Section A specifies the EvIR node set and Section B records the per-node C++ mappings. This section explains the lowering model those mappings sit inside: the compilation pipeline, the ownership-handle representation, the statement and abstraction lowering, concurrency, the foreign-function boundary, the generated entry point, diagnostics, and kernel-build facts. It carries the narrative that was Article II of the constitution before the EvIR specification was split into this document.

Part C.i — The compilation pipeline

The canonical compiler is a linear pipeline from Envzn source to a native executable. Source text is first tokenized into a stream of tokens carrying position information. The token stream is then parsed, by recursive descent, into an abstract syntax tree. The tree is then analyzed — the analyzer resolves types, checks the move and lock and reference rules, and verifies interface satisfaction, and it is the analyzer's passes, rather than any separate tool, that serve as the language's lint layer. The analyzed tree is then built into EvIR (build_ir) and the EvIR is emitted as C++20 (compiler/evir/emitter.py). The emitted C++ is finally handed to the backend, which invokes clang++ with -std=c++20 to produce the executable.

Around that per-translation-unit pipeline sits the module driver, which performs the work C.vi describes. It loads manifests, resolves dependencies in topological order, merges a module's source files into one compilation unit, emits the combined C++, and invokes the backend with the dependent libraries linked. All diagnostics are reported before C++ emission is attempted, so that a downstream C++ error never obscures an Envzn one. The canonical compiler is the Python implementation under bin/; a second, trimmer compiler and an in-progress self-hosted compiler exist, and where they diverge from the canonical one the divergence is treated as catching-up work, not as a second opinion.

Part C.ii — Types and memory: the ownership-handle model

The primitive types lower to fixed-width C++ types. The signed and unsigned integers from 8 to 64 bits become the <cstdint> exact-width types. The 128-bit int128 and uint128 lower to the compiler built-ins __int128 and unsigned __int128, which need no header. No libc path renders or parses a 128-bit integer, so the kernel does both through a hand-rolled decimal-and-base conversion. float32 and float64 become float and double, boolean becomes bool, and byte and binary become uint8_t. The char family lowers as three distinct C++ types, deliberately not C++'s 8-bit char — char8 becomes char8_t, char16 becomes char16_t, and char32 (the canonical name char resolves to) becomes char32_t. A character literal lowers to a UTF-32 literal, so 'a' emits as U'a'. These aliases are emitted at global scope rather than inside the kernel namespace, because they are language-level primitives and a developer expects int32 to mean the same thing in every module.

A class type lowers to a heap allocation reached through an owning handle. The default owning handle is _ev_unique<T>, a non-copyable smart handle: its non-copyability at the C++ type level is what makes an accidental second owner a compile error in the emitted code, not merely in the analyzer. The allocation is split in two — a separate T allocation and a small separate control block, _ev_ctrl<T>, of roughly a dozen bytes. The control block carries an atomic alive flag, an atomic weak_count, and an atomic strong_count. The alive flag records whether the T is still valid. The weak_count counts the _ev_weak<T> observers, each incrementing it on construction or copy and decrementing it on destruction. The control block is freed only when that count reaches zero, which guarantees no observer ever reads a deallocated control block. A type that is the referent of an escaping strong reference is shared-eligible, and its strong owners are _ev_shared<T>. That is a copyable handle: it increments strong_count on copy or bind, decrements it on drop, and destroys the T when the strong count reaches zero. A _ev_unique<T> and a _ev_shared<T> are the two owning shapes; a given binding is one or the other, never both, and the analyzer's disposition decision of I.I.v chooses which. Only shared-eligible types pay for the strong handle — every other class stays _ev_unique<T> at zero refcount cost. Primitives, String, STATUS, enum cases, and STRUCT fields are value types and are emitted inline. Stack-frame exit releases owned heap objects in reverse declaration order through the ordinary RAII chain.

A REFERENCE T and a MUTABLE REFERENCE T lower to raw C++ pointers — T const* and T* respectively — and carry no control block and no reference count. This is sound precisely because the reference checker of I.I.v has already proved, at compile time, that the reference cannot outlive its referent and cannot alias a conflicting access. The runtime therefore needs no check, and a reference costs exactly a pointer. The exception is a reference field the checker has classified as strong rather than as a borrow — an escaping SHARED MUTABLE REFERENCE — which lowers to a _ev_shared<T> owner. Reference parameters never escape, so they are always borrows and always raw pointers. The parameter-passing rules of I.I.vi lower as follows:

A borrow is a raw pointer, not an owning handle. The earlier ABI passed a class parameter as const _ev_unique<T>& — an owning handle by const reference — which is a category error, because a borrow does not own what it observes, and it made legal programs uncompilable: the only upcast on an owning handle is a move, which a borrow must not perform, so a concrete handle could not be passed to a parameter of a base or interface type, and a borrowed element could not be passed at all. A raw pointer upcasts implicitly, binds a borrowed referent, and keeps EMPTY representable as nullptr, so IS VALID still works and the memory-safety floor of I.A is not traded away.

An ordinary class borrow is T* rather than const T* deliberately. The old const _ev_unique<T>& was const on the handle, not on the pointee — operator-> handed back a non-const T* — so a borrowed parameter has always been able to call the instance's MODIFY methods, and constifying the pointee would smuggle a new restriction into a bug fix. The text types are the exception: String and ByteBuffer are immutable by the type convention of I.D.vi and expose no MODIFY method, so that concern cannot arise and their borrow is const T* — which is also what allows a read-only REFERENCE local, itself a const T*, to bind to one.

Part C.iii — Statements, expressions, and control flow

Most expressions lower directly. The arithmetic and comparison operators become their C++ equivalents, as do the keyword bitwise, shift, and boolean operators. A derived operator — one a type gained by implementing an operator interface of I.K.iv — lowers to a call of the interface method the compiler derived it from. A CREATE lowers to a heap allocation through _ev_unique<T>, followed by the matching INIT call. A := move lowers to a C++ move of the handle; a = value copy to direct initialization, or to the explicit CREATE or clone() the source contained; and a =@ reference to taking the address of the place expression.

A STATUS lowers to the _EvStatus struct, which carries the outcome, a message String, and an int32_t code defaulting to 0. The pipe-XOR shape of I.M lowers to a C++ std::tuple of the success slots followed by the trailing _EvStatus — RETURNS (A a, B b | STATUS s) becomes a std::tuple<A, B, _EvStatus>. The consumption form lowers to an if whose condition tests the tuple's _EvStatus slot, with the result tokens resolving to std::get reads of that temporary: $=[i] is std::get<i>(temp), $# is std::get<status_idx>(temp).code, and $! is std::get<status_idx>(temp).message. MATCH lowers according to its subject — an enum or GROUP to a switch or std::variant visitation, a possibly-EMPTY value to a presence test over its two arms, and a condition-form MATCH to an if/else if chain.

FOR IN lowers by the shape of the iterable, in two forms that share one surface. A class collection or a user class implementing Iterator OF T takes the iterator form: a loop FOR T x IN coll { body } becomes, in effect, an owned iterator obtained from coll->iterator(), a WHILE over hasNext(), and a per-iteration next() whose pipe-XOR result binds x as a non-owning reference into the collection:

{
    Iterator OF T _it := coll->iterator()
    WHILE _it->hasNext() {
        IF _it->next() THEN {
            REFERENCE T x =@ $=
            body
        } ELSE {
            PANIC Error("FOR/IN invariant: next() yielded a failure after hasNext() was true")
        }
    }
}

A raw array — T[], T[N], or T[N+], as distinct from the Array[T] wrapper class — takes the index form instead. The loop is driven by an index over the array buffer, with the loop variable bound to a borrow pointer into that buffer, and the iterable expression evaluated exactly once (it may be side-effecting). The reason is that the shared loop body is lowered for a REFERENCE variable it dereferences, for every element kind including value elements, and a value array's by-value next() cannot hand back a stable pointer to dereference. The two forms are not observably different to a program: both visit every element in order and bind a non-owning reference to it.

The implicit iterator of the first form is owned by the loop and dropped at loop exit, and that lowering serves a kernel collection and a user class that implements Iterator OF T alike. As an optimization with no observable effect, the compiler may inline the iterator's method bodies in place of virtual dispatch when the static type of the implicit iterator resolves to a FINAL CLASS. A program may not depend on whether the inlining fires.

The IDENTITY(subject) reflection intrinsic (I.K.iii(e)) introduces no IR node of its own — it reuses IrCreate. The analyzer computes the Identity field values from the subject's static type and binding. The IR builder then synthesizes an IrCreate of the kernel STRUCT Identity, whose arguments are those values as literal nodes: IrStringLit, IrBoolLit, and an IrArrayLit of IrStringLit for the lenses ancestor list. It then lowers exactly like any struct value-constructor call. No new node, and no emit-phase decision: by construction the value is legal and fixed.

Part C.iv — Abstractions

A class lowers to a C++ class. Its data fields become members and its methods become member functions. The MODIFY distinction of I.K.vi lowers to the C++ const qualifier: a read-only Envzn method emits as a const member function, a MODIFY method as a non-const one. The const-correctness Envzn enforces at its own level is thereby carried into the emitted code. INIT becomes a constructor and CLEANUP, together with the field-destruction chain, becomes the destructor. FINAL emits the C++ final specifier, which both forbids subclassing and lets the C++ compiler devirtualize and inline calls — the mechanism behind the optional iterator inlining of C.iii.

An interface lowers to an abstract C++ class of pure virtual functions, and a class that implements one gains a vtable. A call through an interface-typed reference is an ordinary virtual call — one pointer indirection — and that is the whole runtime cost of the polymorphic collections of I.K.vii. A GROUP lowers to a std::variant over its member types; a group member that recurses through Box lowers that Box to a _ev_unique indirection, which is what breaks the otherwise self-referential variant. An enum lowers by form: a simple enum to a C++ enumeration, a raw-value enum to one carrying its primitive values, and an associated-value enum to a tagged representation that a MATCH destructures.

The library aggregates are implemented internally with C++ templates, which is how Envzn offers parameterized collections without exposing user-defined generics. Array[T] backs onto the T[] storage primitive — its INTERNAL T[] data field lowers to EvArray<T>, which resolves the _ValueArray<T> value-array for a blittable T and the _ObjectArray<_ev_unique<T>> object-array for a class T. An array literal lowers to a C++ brace-init {…} for a value-element array, since _ValueArray has an initializer_list constructor. A non-empty object-element array literal cannot: an array of move-only owning handles has no initializer_list form. It lowers instead through the free factory _ev_object_array_of(e0, e1, …), which move-appends each element onto a fresh _ObjectArray through its existing grow-assign. An empty literal is a plain {} for either backing. Dictionary is a pure INTERFACE Dictionary[K, V, H] with pure-Envzn implementations behind it (ChainedHashDictionary, RedBlackTreeDictionary, ProHashDictionary); the compiler no longer special-cases it, and hashing is pluggable through the H (Hasher) type parameter rather than a C++ functor. Set[V, H] is likewise a pure-Envzn class wrapping a Dictionary, so neither Set nor Dictionary backs onto a C++ unordered container. The iterators the collections hand out are concrete FINAL classes, one per collection, and their FINAL-ness is what permits the loop-body inlining of C.iii.

Part C.v — Concurrency

CONCURRENT { … } lowers to a structured task scope — an _ev_task_scope RAII object over the block body that joins every task it launched before it unwinds. A PARALLEL { … } block lowers to a task launched on a std::thread registered with the innermost enclosing scope, and the task body emits as the callable the thread runs. The capture restrictions of I.L.vii are enforced in the analyzer before emission, so the emitted lambda captures only what the model permits. SYNCHRONIZED(lock) { … } lowers to a std::lock_guard over the lock's native mutex, held for the body and released automatically on every exit path — fall-through, RETURN, BREAK, or a PANIC unwinding through it.

Channel[T] lowers to a typed, bounded message queue with its synchronization state; Broker[T] to the lock-free publish-index-and-per-subscriber-ring structure of I.L.iv; Mutex[T] to a mutex guarding interior storage reachable only inside its SYNCHRONIZED block; Future[T] to an eventually-ready cell sharing the pipe-XOR consumption shape; Atomic[T] to a std::atomic over the primitive width; and WorkerPool[T] to the kernel's pool class built over those primitives. The low-level synchronization primitives the kernel needs — a mutex, a condition variable, an atomic, a raw thread handle — are not expressible as ordinary Envzn classes, because the underlying C++ standard-library types delete their copy and move operations. The kernel reaches them through the FOREIGN_TYPE BIND mechanism of C.vi, as a small family of _cxx-prefixed types: _cxxmutex, _cxxcondvar, _cxxatomic[T], _cxxrawthread. Each binds the corresponding C++ standard type by value, and each emits its parameters by reference rather than by value, precisely because those C++ types cannot be copied.

Part C.vi — Modules, linkage, and the foreign-function boundary

Each module's emitted C++ is wrapped in a namespace. A non-kernel module emits as namespace modulename { using namespace ENVZN; … }, and the using directive is what lets kernel types keep their bare names inside the module's emitted code. The kernel itself emits inside namespace ENVZN, with the one exception of the primitive numeric aliases, which stay at global scope as C.ii records. The module driver compiles a module in five steps. It loads the manifest for identity, target, dependencies, and foreign metadata. It resolves and recursively compiles the dependencies in topological order. It merges the source files into one compilation unit, where a duplicate type name across two files is an error. It emits the combined C++, and invokes clang++ -std=c++20 with the dependent libraries linked. An executable target produces a binary, and the compiler appends a generated int main() under the rules of C.vii. A shared_library target produces a .dylib together with a generated .headers file that lists every public, non-INTERNAL declaration and so forms the authoritative public surface a dependent compiles against.

The foreign-function boundary lowers as follows. A FOREIGN BIND declaration of a C function is type-checked against its Envzn signature alone; the compiler never reads C header content. In the ordinary case it lowers to a direct call of the bare C symbol, so a binding named open lowers FOREIGN::open(...) to ::open(...). The compiler synthesizes the conversion at each boundary type. Three markers change the lowering. The LOAD parameter modifier declares a value-array parameter write-through, so the C function writes through the storage pointer. A binding marked SETS_ERRNO(sentinel) emits a wrapper that turns an errno into a STATUS FAILURE, making it a pipe-XOR producer. A return marked $*, or $(freer()), emits a wrapper that copies the returned C string and frees the raw pointer, so the free is compiler-generated and inseparable from the call. FOREIGN is an Envzn-side greppability marker only — no FOREIGN C++ namespace is emitted. Every type at the boundary is an Envzn type mapped to the C ABI by a fixed table:

ByteBuffer is parameter-only: RETURNS ByteBuffer is a compile error, because a single C return value cannot carry both a pointer and a length. A C library struct — struct stat, struct sockaddr — has a layout fixed by system headers, and never crosses the boundary. A C function that needs one is reached through a module-supplied native shim, which speaks only boundary types in its own signature. FOREIGN BIND CONSTANT binds a single integer macro (e.g. O_RDONLY) through a small C shim that re-exports it as a named symbol. The LOAD shape table and the boundary rules are Article I.N(h) of the Constitution; the manifest conventions and the V2 boundary extensions are outside this spec.

Part C.vii — The generated entry point

Every executable module names one entry class, and the compiler generates the main() that runs it. The entry class is named in a sibling file, entrypoint.json, carrying a single class field. Each of the following is a compile error: an executable module that lacks the file, a shared-library module that has it, a malformed file, or a named class that does not exist, does not implement ThreadStarter, or does not declare INIT(String[] argv).

{ "class": "Main" }

The entry class implements ThreadStarter, the single-method interface — METHOD start() RETURNS STATUS — that the program's main thread and every spawned worker thread share. The entry class receives the process arguments through INIT(String[] argv). The body of that INIT is restricted by diagnostic E6037 to plain self-field assignment statements, so it cannot quietly become a second entry point. The language guarantees that start() is the first line of user-controlled logic. The compiler appends an int main() that builds a String[] from the operating system's argv, constructs the entry class with it, and calls start(). It translates the returned STATUS to a POSIX exit code: SUCCESS to 0, PARTIAL_SUCCESS and FAILURE to 1. The whole sequence is wrapped in a C++ try with three narrowing catch arms: Envzn's Error first, then std::exception, then a catch-all. Each writes a diagnostic to standard error and exits 1, so an uncaught exception produces a message rather than a silent std::terminate.

Part C.viii — Error detection and reporting

The compiler detects errors at every stage of the pipeline, and the stage at which an error is found determines both its category and how the compiler recovers from it well enough to keep finding more.

Every diagnostic carries four things: a source location of file, line, and column; an error level, either error, which blocks compilation, or warning, which does not; a quoted snippet of the offending line with a caret beneath the span; and, where the fix is clear, a suggestion. A diagnostic is identified by a stable E#### code, and the codes named throughout Article I are those identifiers. All errors are reported before C++ emission is attempted, so that a downstream clang++ error cannot mask the Envzn error that caused it.

A location is a range, not a point: start_line/start_col and end_line/end_col, 1-based and counted in Unicode code points. A point is the degenerate range whose end equals its start, so a diagnostic that knows only where a problem begins is expressible without a second shape. The frame is drawn only where the source is readable and the column is known; where either is missing the diagnostic prints its location line alone rather than a partial frame, because a diagnostic must never fail while reporting a failure. The caret is placed by display column — a tab advances to the next multiple of eight, and an East-Asian Wide or emoji glyph occupies two cells — which is not the stored column on any line containing either.

Where a single literal edit resolves the diagnostic, it is offered as a help: line beneath the remedy, and the same edit is machine-applicable. Most diagnostics have none, and that is the expected outcome: the remedy for a type error or a missing contract is a decision, not a substitution.

error [E1174] parse:numeric-literal-malformed: `0x` must be followed by hex digits
  ╭─ examples/hello.ev:6:19
6 │         int32 h = 0x
  │                   ^
  ╰─
  at examples/hello.ev:6:19
  help: replace with `0x1F`

The same diagnostics are available as machine-readable records under --diagnostics=json, shaped as LSP Diagnostic objects — 0-based lines and UTF-16 character offsets, with any fix carried as a TextEdit. Everything Envzn-specific is namespaced under evzn. in the record's data field, which LSP defines as opaque passthrough, so an editor consumes the stream without a translation layer. The document is always emitted, even when empty, so a consumer can distinguish a clean build from a compiler that stopped before it could report.

Part C.ix — Kernel implementation notes

The kernel — the ENVZN module — is compiled as a shared library that every Envzn program links against. It publishes a single canonical header, which the generated C++ of every module includes.

The kernel is authored as Envzn source — roughly one hundred ten .ev files — and the compiler emits from them a per-class header apiece, alongside the hand-written floor and its native glue, all of which the canonical header includes. This is the result of the demagic effort, a staged project to replace hand-written C++ kernel class bodies with emitted ones. A collection or utility that was once a block of C++ in the kernel header is now an ordinary .ev file the compiler lowers like any other. The canonical header retains only the host runtime glue that genuinely cannot be authored in Envzn — the formatting and hashing helpers, the four-form String and Binary primitive machinery, and the low-level _cxx* concurrency types of C.v. The kernel holds to one hard rule: it has no dependency on any external package, and an optional system dependency — OpenSSL, SQLite, a regex library — belongs in the module that consumes it, never in the kernel.

End of specification. Section A specifies 92 EvIR nodes in 14 groups; Section B records 518 TSV-traced lowering rows; Section C is curated narrative. Regenerate Sections A and B with the spec-spec generator.