compiler 0.0.2-preview.1

The Zena self-hosted compiler

Readme Files Dependencies Versions

compiler#

The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).

Usage#

Parsing a Single File#

Use compiler/parser to parse Zena source text into an AST (Module):

import { parse } from 'compiler/parser';

let ast = parse('export let answer = 42;', 'example.zena');

Loading and Checking a Program#

Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:

import {
  createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';

let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
  stdlibRoot,
  packages,
});

let result = await compiler.compile({
  entry: '/workspace/main.zena',
  target: 'host',
});
let checked = checkCompilation(result);

Compiling a File to WebAssembly#

Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:

import { compileFile } from 'compiler/compile-file';

let ok = await compileFile({
  entry: 'src/main.zena',
  outPath: 'out/main.wasm',
  stdlibRoot: '/stdlib',
});

Libraries#

  • compiler / compiler/compiler — compiler entry point (Compiler, createCompiler, checkCompilation, ProgramCheckResult)
  • compiler/compile-file — end-to-end file compilation (compileFile, CompileFileOptions)
  • compiler/tokenizer — lexer and token definitions (tokenize, Token, TokenType)
  • compiler/parser — recursive-descent parser (parse, Parser)
  • compiler/ast — AST node definitions (Node, Module, Statement, Expression, TypeAnnotation)
  • compiler/visitor — AST traversal helpers (walk, Visitor)
  • compiler/scope — lexical scope and symbol resolution (ScopeBuilder, ScopeResult, Symbol)
  • compiler/checker — static type checker (checkModule, CheckResult)
  • compiler/semantic-model — semantic queries over a checked module (SemanticModel)
  • compiler/types — compiler type representations (Type, ClassType, FunctionType, typeToString)
  • compiler/diagnostics — compiler diagnostics and source spans (Diagnostic, DiagnosticCode, DiagnosticSeverity, SourceSpan)
  • compiler/package-manifest — zena-package.json manifest and workspace loader (loadWorkspace, loadPackageMap)
  • compiler/module-resolver — package and relative module specifier resolution (ModuleResolver, PackageConfig)
  • compiler/library-loader — module graph loader (LibraryLoader, CompilerHost, SourceFile)
  • compiler/codegen/binary-generator — WebAssembly GC binary emitter (BinaryGenerator)
  • compiler/codegen/wat-generator — WebAssembly Text (WAT) emitter (WatGenerator)

License#

MIT

34.5 KiB Raw
/**
 * Intrinsic call lowering: one function per intrinsic, with
 * lowerIntrinsic as the single name -> function router for every
 * call-position intrinsic (the prelude array builtins plus the
 * @intrinsic declare functions like eq/hash). FunctionLowerer's
 * surface is private and importing it here would create an import
 * cycle with lowering.zena, so each lowering receives the narrow
 * slice it needs as LoweringContext: the builder plus closures over the
 * lowerer's expression machinery. The eq/hash implementations stay
 * lowerer-side for now — they share the primitive cluster with the
 * case-class ==/hashCode synthesizers — and arrive here as closures.
 */
import { CallExpression, Expression, NumberLiteral, UnaryExpression } from '../../ast.zena';
import { ValType, ValTypeI32, ValTypeI8, ValTypeI16, ValTypeV128, ValTypeVoid, isRefValType } from '../wasm.zena';
import {
  SimdInstruction, SimdShape, SimdResult, simdInstruction, simdArgCount,
  simdLaneCount,
} from '../../simd.zena';
import { parseI32WithHex } from '../codegen-utils.zena';
import { arrayElementType, isSignedNarrowIntType, isVoidOrNeverType, FunctionType, representsRestricted } from '../../types.zena';
import {
  WasmFunction, WasmArray, WasmTag, isValSubtype, asWasmArray,
} from '../wasm-module.zena';
import { ValTypeI64, ValTypeF32, ValTypeF64 } from '../wasm.zena';
import { IrRefFunc } from './ir.zena';
import { IrOp, IrRefTag, IrRefType, isWideMulOp } from './ir.zena';
import { LoweringContext } from './lowering-context.zena';
import { lowerEqIntrinsic, lowerHashIntrinsic } from './equality.zena';
import { convertValueToString } from './templates.zena';
import { lowerExpr } from './lowering.zena';
import { emitReleaseOwned } from './control-flow.zena';
import { growable } from 'zena:core';

/**
 * The slice of FunctionLowerer the intrinsic lowerings need. `fail`
 * throws ZirUnsupported on the lowerer's side; its i32 result is never
 * actually produced — it only lets bail sites sit in value positions.
 * `lowerEq`/`lowerHash` are the type-directed equals/hash lowerings,
 * which live on the lowerer because they share primitives with the
 * case-class synthesizers.
 */
/** Memory load: addr operand; alignment hint matches streaming. */
function lowerMemLoad(cx: LoweringContext, call: CallExpression, op: IrOp, resultVt: ValType, align: i32) {
  let addr = lowerExpr(cx, call.args[0], null);
  return cx.b.emit(op, resultVt, addr, align);
}

/** Memory store: addr + value operands; align matches streaming. */
function lowerMemStore(cx: LoweringContext, call: CallExpression, op: IrOp, align: i32) {
  let addr = lowerExpr(cx, call.args[0], null);
  let value = lowerExpr(cx, call.args[1], null);
  let pair = growable<i32>([addr, value]);
  return cx.b.emitVoid(op, cx.b.pushExtra(pair), align);
}

/** A call-position intrinsic that is one wasm instruction: lowers the
 * arguments in order and emits the op. Operand agreement is the
 * checker's (and finally the verifier's/validator's) problem. */
function lowerInstr(cx: LoweringContext, call: CallExpression, op: IrOp, resultVt: ValType): i32 {
  if (call.args.length == 1) {
    let a = lowerExpr(cx, call.args[0], null);
    return cx.b.emit(op, resultVt, a, -1);
  }
  if (call.args.length == 2) {
    let a = lowerExpr(cx, call.args[0], null);
    let c = lowerExpr(cx, call.args[1], null);
    return cx.b.binary(op, resultVt, a, c);
  }
  cx.fail('intrinsic arity');
}

/** cancel.raise: a throw on the cancellation tag — the channel user
 * `catch` cannot observe (docs/design/cancellation.md). No payload is
 * set: nothing may observe a cancellation, so there is nothing to
 * carry. RTA ensures the tag when the intrinsic is reached; a miss
 * here is a reachability bug, not a fallback site. */
function lowerCancelRaise(cx: LoweringContext, call: CallExpression): i32 {
  let tagOpt = cx.wasm.cancellationTag;
  if (tagOpt == null) {
    // The whole-program gate is closed: nothing can cancel, so this
    // raise site can never run — a cancelled future cannot exist.
    // Emit a trap rather than a tag the program does not carry.
    cx.b.unreachable();
    cx.reachable = false;
    return -1;
  }
  cx.b.throwWithTag(new Array<i32>(),
      cx.b.addRef(new IrRefTag(tagOpt as WasmTag)));
  cx.reachable = false;
  return -1;
}

/** Lowers `e` and requires an array-typed value: (value, its array). */
function arrayOperand(cx: LoweringContext, e: Expression): (i32, WasmArray) {
  let value = lowerExpr(cx, e, null);
  let arrOpt = asWasmArray(cx.valueTypeOf(value));
  if (arrOpt == null) {
    cx.fail('array builtin receiver');
  }
  return (value, arrOpt);
}

/** Lowers `e` and requires an i32 value (indexes, offsets, lengths). */
function indexOperand(cx: LoweringContext, e: Expression) {
  let value = lowerExpr(cx, e, null);
  if (!(cx.valueTypeOf(value) is ValTypeI32)) {
    cx.fail('array builtin index type');
  }
  return value;
}

/** __array_len / __byte_array_length: array.len is width-agnostic. */
function lowerArrayLen(cx: LoweringContext, call: CallExpression) {
  let (arr, _) = arrayOperand(cx, call.args[0]);
  return cx.b.emit(IrOp.array_len, new ValTypeI32(), arr, -1);
}

/** Whether a wasm element type is one of the packed widths. */
function isPackedElement(vt: ValType) {
  return vt is ValTypeI8 || vt is ValTypeI16;
}

/**
 * Whether a packed array's elements should be read sign-extended.
 *
 * The wasm array type cannot answer this: `array<u8>` and `array<i8>`
 * are the same `(array (mut i8))`, and signedness lives on the read
 * instruction. So the semantic element type of the receiver decides,
 * and an unsigned element is the safer default when it cannot be
 * recovered — a zero-extending read of a `u8` is always correct, while
 * a sign-extending read of one silently invents negative values.
 */
function packedArrayElementSigned(cx: LoweringContext, e: Expression): boolean {
  let t = cx.substitutedNodeType(e);
  if (t == null) {
    return false;
  }
  let elem = arrayElementType(t);
  if (elem == null) {
    return false;
  }
  return isSignedNarrowIntType(elem);
}

/**
 * Whether the argument's checked type is zero-width (void/never). A
 * zero-width array element stores as packed i8
 * (typeToStorageValType), so the write builtins have an i32 slot to
 * fill and no value to fill it with: the argument runs for its
 * effects and the slot stores a constant.
 */
function zeroWidthArg(cx: LoweringContext, e: Expression) {
  let t = cx.substitutedNodeType(e);
  return t != null && isVoidOrNeverType(t);
}

/** __array_get: array.get, choosing the packed read for narrow elements. */
function lowerArrayGet(cx: LoweringContext, call: CallExpression) {
  let (arr, arrType) = arrayOperand(cx, call.args[0]);
  let index = indexOperand(cx, call.args[1]);
  if (isPackedElement(arrType.elementType)) {
    // Packed elements unpack to a full i32, zero- or sign-extended to
    // the canonical form the narrow types are carried in.
    let op = if (packedArrayElementSigned(cx, call.args[0])) {
      IrOp.array_get_s
    } else {
      IrOp.array_get_u
    };
    return cx.b.emit(op, new ValTypeI32(), arr, index);
  }
  cx.requireSupported(arrType.elementType, 'array element type');
  let value = cx.b.emit(IrOp.array_get, arrType.elementType, arr, index);
  return cx.reassertNonNull(value, cx.exprVt(call));
}

/** __byte_array_get: packed i8 elements read unsigned (array.get_u). */
function lowerByteArrayGet(cx: LoweringContext, call: CallExpression) {
  let (arr, arrType) = arrayOperand(cx, call.args[0]);
  let index = indexOperand(cx, call.args[1]);
  if (!(arrType.elementType is ValTypeI8)) {
    cx.fail('byte builtin on non-byte array');
  }
  return cx.b.emit(IrOp.array_get_u, new ValTypeI32(), arr, index);
}

/** __array_set: array.set, taking a plain i32 for packed elements. */
function lowerArraySet(cx: LoweringContext, call: CallExpression) {
  let (arr, arrType) = arrayOperand(cx, call.args[0]);
  let index = indexOperand(cx, call.args[1]);
  if (isPackedElement(arrType.elementType)) {
    // array.set on a packed element takes an i32 and truncates to the
    // stored width, which is exactly the narrow value's canonical form.
    var packedValue = -1;
    if (zeroWidthArg(cx, call.args[2])) {
      lowerExpr(cx, call.args[2], null);
      packedValue = cx.b.constI32(0, new ValTypeI32());
    } else {
      packedValue = lowerExpr(cx, call.args[2], new ValTypeI32());
      if (!(cx.valueTypeOf(packedValue) is ValTypeI32)) {
        cx.fail('array builtin write type');
      }
    }
    let packedIdx = cx.b.pushExtra(threeValues(arr, index, packedValue));
    return cx.b.emitVoid(IrOp.array_set, packedIdx, -1);
  }
  cx.requireSupported(arrType.elementType, 'array element type');
  let value = lowerExpr(cx, call.args[2], arrType.elementType);
  if (!isValSubtype(cx.valueTypeOf(value), arrType.elementType)) {
    cx.fail('array builtin write type');
  }
  let tripleIdx = cx.b.pushExtra(threeValues(arr, index, value));
  return cx.b.emitVoid(IrOp.array_set, tripleIdx, -1);
}

/** __byte_array_set: packed i8 elements take plain i32 values. */
function lowerByteArraySet(cx: LoweringContext, call: CallExpression) {
  let (arr, arrType) = arrayOperand(cx, call.args[0]);
  let index = indexOperand(cx, call.args[1]);
  if (!(arrType.elementType is ValTypeI8)) {
    cx.fail('byte builtin on non-byte array');
  }
  let value = lowerExpr(cx, call.args[2], new ValTypeI32());
  if (!(cx.valueTypeOf(value) is ValTypeI32)) {
    cx.fail('array builtin write type');
  }
  let tripleIdx = cx.b.pushExtra(threeValues(arr, index, value));
  return cx.b.emitVoid(IrOp.array_set, tripleIdx, -1);
}

/**
 * The array type both new-family builtins allocate: the call's own
 * checked type — the same source streaming uses for the array.new
 * type index.
 */
function newResultArray(cx: LoweringContext, call: CallExpression): (ValType, WasmArray) {
  let resultVt = cx.exprVt(call);
  let arrTypeOpt = asWasmArray(resultVt);
  if (arrTypeOpt == null) {
    cx.fail('array builtin result type');
  }
  return (resultVt, arrTypeOpt);
}

/**
 * `defaultValue<T>()`: what an empty `WithDefault<T>` slot holds, null
 * at a reference `T` and zero at a primitive one. The call's type at
 * this specialization is the closed `WithDefault<T>`, so its value type
 * says which.
 */
function lowerDefaultValue(cx: LoweringContext, call: CallExpression): i32 {
  let t = cx.substitutedNodeType(call);
  if (t != null && isVoidOrNeverType(t)) {
    // `WithDefault<void>` is `void`: no value, which is lowering.zena's
    // NO_VALUE (a module value, so it does not cross the import cycle).
    return -1;
  }
  let vt = cx.exprVt(call);
  if (isRefValType(vt)) {
    return cx.b.emit(IrOp.ref_null, vt, -1, -1);
  }
  return match (vt) {
    case ValTypeI32: cx.b.constI32(0, vt)
    case ValTypeI64: cx.b.constI64(0 as i64, vt)
    case ValTypeF32: cx.b.constF32(0.0, vt)
    case ValTypeF64: cx.b.constF64(0.0, vt)
    case _: cx.failValue('defaultValue of this type')
  };
}

/**
 * `isFirstClass<T>()`: a constant in each specialization, true where
 * `T` is first-class. It is false wherever a take would empty a slot
 * (representsRestricted), so the two always agree: false at `Own<R>`
 * and `Borrow<R>`, true at `Unmanaged<R>`.
 */
function lowerIsFirstClass(cx: LoweringContext, call: CallExpression): i32 {
  let calleeType = cx.substitutedNodeType(call.callee);
  if (!(calleeType is FunctionType)) {
    return cx.failValue('isFirstClass callee type');
  }
  let ft = calleeType as FunctionType;
  let args = ft.typeArguments;
  if (args == null || args.length != 1) {
    return cx.failValue('isFirstClass type argument');
  }
  let firstClass = !representsRestricted(args[0]);
  return cx.b.constI32(if (firstClass) 1 else 0, new ValTypeI32());
}

/**
 * `releaseOwned<T>(value)`: releases what `value` owns, as its implicit
 * drop would, at this specialization's `T` (control-flow.zena
 * emitReleaseOwned).
 */
function lowerReleaseOwned(cx: LoweringContext, call: CallExpression): i32 {
  let calleeType = cx.substitutedNodeType(call.callee);
  if (!(calleeType is FunctionType)) {
    return cx.failValue('releaseOwned callee type');
  }
  let ft = calleeType as FunctionType;
  let args = ft.typeArguments;
  if (args == null || args.length != 1 || call.args.length != 1) {
    return cx.failValue('releaseOwned arguments');
  }
  let value = lowerExpr(cx, call.args[0], null);
  emitReleaseOwned(cx, value, args[0]);
  return -1;
}

/**
 * `shareReference(value)`: the same reference, which the checker lets
 * the caller keep beside the argument (checker/ownership.zena
 * sharesArgument). Nothing happens at run time.
 */
function lowerShareReference(cx: LoweringContext, call: CallExpression) {
  if (call.args.length != 1) {
    return cx.failValue('shareReference arguments');
  }
  return lowerExpr(cx, call.args[0], null);
}

/** __array_new: array.new with an explicit init value. */
function lowerArrayNew(cx: LoweringContext, call: CallExpression) {
  let (resultVt, arrType) = newResultArray(cx, call);
  let length = indexOperand(cx, call.args[0]);
  if (isPackedElement(arrType.elementType)) {
    // As with array.set, the initializer crosses as an i32 and the
    // instruction truncates to the packed width.
    var packedInit = -1;
    if (zeroWidthArg(cx, call.args[1])) {
      lowerExpr(cx, call.args[1], null);
      packedInit = cx.b.constI32(0, new ValTypeI32());
    } else {
      packedInit = lowerExpr(cx, call.args[1], new ValTypeI32());
      if (!(cx.valueTypeOf(packedInit) is ValTypeI32)) {
        cx.fail('array builtin init type');
      }
    }
    let packedPair = cx.b.pushExtra(twoValues(length, packedInit));
    return cx.b.emit(IrOp.array_new, resultVt, packedPair,
        cx.b.addRef(new IrRefType(arrType)));
  }
  cx.requireSupported(arrType.elementType, 'array element type');
  let init = lowerExpr(cx, call.args[1], arrType.elementType);
  if (!isValSubtype(cx.valueTypeOf(init), arrType.elementType)) {
    cx.fail('array builtin init type');
  }
  let pairIdx = cx.b.pushExtra(twoValues(length, init));
  return cx.b.emit(IrOp.array_new, resultVt, pairIdx,
      cx.b.addRef(new IrRefType(arrType)));
}

/** __array_new_empty / __byte_array_new: array.new_default. */
function lowerArrayNewDefault(cx: LoweringContext, call: CallExpression) {
  let (resultVt, arrType) = newResultArray(cx, call);
  let length = indexOperand(cx, call.args[0]);
  let pairIdx = cx.b.pushExtra(twoValues(length, -1));
  return cx.b.emit(IrOp.array_new, resultVt, pairIdx,
      cx.b.addRef(new IrRefType(arrType)));
}

/**
 * __byte_array_copy: argument order (dest, destOff, src, srcOff, len)
 * matches array.copy's operand order exactly.
 */
function lowerByteArrayCopy(cx: LoweringContext, call: CallExpression) {
  let (dest, destType) = arrayOperand(cx, call.args[0]);
  let destOff = indexOperand(cx, call.args[1]);
  let (src, srcType) = arrayOperand(cx, call.args[2]);
  let srcOff = indexOperand(cx, call.args[3]);
  let len = indexOperand(cx, call.args[4]);
  if (!(destType.elementType is ValTypeI8) ||
      !(srcType.elementType is ValTypeI8)) {
    cx.fail('byte builtin on non-byte array');
  }
  let tuple = growable<i32>([dest, destOff, src, srcOff, len]);
  let tupleIdx = cx.b.pushExtra(tuple);
  return cx.b.emitVoid(IrOp.array_copy, tupleIdx, -1);
}

function twoValues(a: i32, b: i32): GrowableArray<i32> {
  let out = growable<i32>([a, b]);
  return out;
}

function threeValues(a: i32, b: i32, c: i32): GrowableArray<i32> {
  let out = growable<i32>([a, b, c]);
  return out;
}

/** memory.grow(pages) -> previous size in pages. */
function lowerMemoryGrow(cx: LoweringContext, call: CallExpression) {
  let pages = lowerExpr(cx, call.args[0], null);
  return cx.b.emit(IrOp.memory_grow, new ValTypeI32(), pages, -1);
}





// -- The wide-arithmetic proposal ------------------------------------------
//
// Four instructions, each two i64 operands-or-pairs in and two i64 out
// (low half first). `WasmModule.wideArithmetic` picks between emitting
// them and emitting the sequence they replace; both produce the same
// two values for every input, which is what makes turning the flag on
// a decision about size and speed rather than about semantics.
//
// The polyfills are the textbook ones. For the multiplies the low half
// is just `i64.mul` — wasm's wrapping multiply IS the low 64 bits of
// the 128-bit product — and only the high half needs the four
// 32x32->64 partial products.

function i64vt(): ValType {
  return new ValTypeI64();
}

/** `x op y` on i64s. */
function i64bin(cx: LoweringContext, op: IrOp, x: i32, y: i32) {
  return cx.b.binary(op, i64vt(), x, y);
}

/** An i64 constant. */
function i64const(cx: LoweringContext, v: i64) {
  return cx.b.constI64(v, i64vt());
}

/** The low 32 bits of an i64, zero-extended. */
function lowHalf(cx: LoweringContext, x: i32) {
  return i64bin(cx, IrOp.i64_and, x, i64const(cx, 0xFFFFFFFF as i64));
}

/** The high 32 bits of an i64, shifted down (unsigned). */
function highHalf(cx: LoweringContext, x: i32) {
  return i64bin(cx, IrOp.i64_shr_u, x, i64const(cx, 32 as i64));
}

/**
 * The high 64 bits of the unsigned 128-bit product x*y, from the four
 * 32x32->64 partial products. `mid` cannot overflow: it is at most
 * (2^32-1) + 2*(2^32-1) < 2^34.
 */
function mulHighU(cx: LoweringContext, x: i32, y: i32) {
  let x0 = lowHalf(cx, x);
  let x1 = highHalf(cx, x);
  let y0 = lowHalf(cx, y);
  let y1 = highHalf(cx, y);
  let p00 = i64bin(cx, IrOp.i64_mul, x0, y0);
  let p01 = i64bin(cx, IrOp.i64_mul, x0, y1);
  let p10 = i64bin(cx, IrOp.i64_mul, x1, y0);
  let p11 = i64bin(cx, IrOp.i64_mul, x1, y1);
  let mid = i64bin(cx, IrOp.i64_add,
      i64bin(cx, IrOp.i64_add, highHalf(cx, p00), lowHalf(cx, p01)),
      lowHalf(cx, p10));
  return i64bin(cx, IrOp.i64_add,
      i64bin(cx, IrOp.i64_add, p11, highHalf(cx, p01)),
      i64bin(cx, IrOp.i64_add, highHalf(cx, p10), highHalf(cx, mid)));
}

/**
 * The signed high half, from the unsigned one: reading a negative
 * operand as unsigned overcounts the product by 2^64 times the other
 * operand, so subtract each operand masked by the other's sign
 * (`x >> 63` is 0 or all-ones).
 */
function mulHighS(cx: LoweringContext, x: i32, y: i32) {
  let hi = mulHighU(cx, x, y);
  let sx = i64bin(cx, IrOp.i64_shr_s, x, i64const(cx, 63 as i64));
  let sy = i64bin(cx, IrOp.i64_shr_s, y, i64const(cx, 63 as i64));
  return i64bin(cx, IrOp.i64_sub,
      i64bin(cx, IrOp.i64_sub, hi, i64bin(cx, IrOp.i64_and, sx, y)),
      i64bin(cx, IrOp.i64_and, sy, x));
}

/**
 * A 0-or-1 i64 from an i64 comparison. `i64.lt_u` leaves an i32, and
 * sign-extending it is exact for 0 and 1.
 */
function carryBit(cx: LoweringContext, op: IrOp, x: i32, y: i32) {
  let cmp = cx.b.binary(op, new ValTypeI32(), x, y);
  return cx.b.emit(IrOp.i64_extend_i32_s, i64vt(), cmp, -1);
}

/** The polyfill for one wide-arithmetic op: [lo, hi]. */
function wideArithPolyfill(
  cx: LoweringContext,
  op: IrOp,
  ops: GrowableArray<i32>
) {
  let out = new Array<i32>();
  if (op == IrOp.i64_mul_wide_u || op == IrOp.i64_mul_wide_s) {
    let x = ops[0];
    let y = ops[1];
    out.push(i64bin(cx, IrOp.i64_mul, x, y));
    out.push(if (op == IrOp.i64_mul_wide_u) {
      mulHighU(cx, x, y)
    } else {
      mulHighS(cx, x, y)
    });
    return out;
  }
  let aLo = ops[0];
  let aHi = ops[1];
  let bLo = ops[2];
  let bHi = ops[3];
  if (op == IrOp.i64_add128) {
    let lo = i64bin(cx, IrOp.i64_add, aLo, bLo);
    // The sum wrapped exactly when it came out below either addend.
    let carry = carryBit(cx, IrOp.i64_lt_u, lo, aLo);
    out.push(lo);
    out.push(i64bin(cx, IrOp.i64_add,
        i64bin(cx, IrOp.i64_add, aHi, bHi), carry));
    return out;
  }
  let lo = i64bin(cx, IrOp.i64_sub, aLo, bLo);
  let borrow = carryBit(cx, IrOp.i64_lt_u, aLo, bLo);
  out.push(lo);
  out.push(i64bin(cx, IrOp.i64_sub,
      i64bin(cx, IrOp.i64_sub, aHi, bHi), borrow));
  return out;
}

/** The ZIR op an `@intrinsic` name in the wide-arithmetic set names. */
function wideArithOp(name: String) {
  return match (name) {
    case 'i64.mul_wide_u': IrOp.i64_mul_wide_u
    case 'i64.mul_wide_s': IrOp.i64_mul_wide_s
    case 'i64.add128': IrOp.i64_add128
    case _: IrOp.i64_sub128
  };
}

/** Whether `name` is one of the four. */
export function isWideArithIntrinsic(name: String): boolean {
  return name == 'i64.mul_wide_u' || name == 'i64.mul_wide_s' ||
      name == 'i64.add128' || name == 'i64.sub128';
}

/**
 * Lowers a wide-arithmetic intrinsic to its two result values. The
 * declarations return `inline (u64, u64)`, so the call must be in a
 * destructuring position — `let (lo, hi) = mulWide(a, b)`. Anywhere
 * else there is no pair of slots to land in, and the checker's
 * inline-tuple type has no single wasm value type to fall back on.
 */
function lowerWideArith(
  cx: LoweringContext,
  name: String,
  call: CallExpression,
  outs: GrowableArray<i32>
) {
  let op = wideArithOp(name);
  let arity = if (isWideMulOp(op)) 2 else 4;
  if (call.args.length != arity) {
    cx.fail(name + ': wrong argument count');
  }
  let ops = new Array<i32>(arity);
  for (var i = 0; i < arity; i += 1) {
    ops.push(lowerExpr(cx, call.args[i], null));
  }
  let results = if (cx.wasm.wideArithmetic) {
    cx.b.wideArith(op, ops, i64vt())
  } else {
    wideArithPolyfill(cx, op, ops)
  };
  for (let r in results) {
    outs.push(r);
  }
}

/**
 * A wasm IMMEDIATE, which is encoded in the instruction rather than
 * read off the stack: it has to be a literal here because there is
 * nowhere else for it to come from. There is no slower dynamic path to
 * fall back to — `i32x4.extract_lane` with a computed index is not a
 * different lowering of the same program, it is a different program
 * (a store, a loop, or a `br_table` over sixteen instructions), and
 * picking one silently would be the wrong call to make on the author's
 * behalf.
 */
function simdImmediate(
  cx: LoweringContext,
  name: String,
  what: String,
  e: Expression,
  limit: i32
) {
  if (!(e is NumberLiteral)) {
    cx.fail(`${name}: ${what} must be a literal`);
  }
  let raw = (e as NumberLiteral).raw;
  let (ok, parsed) = parseI32WithHex(raw);
  if (!ok || parsed < 0 || parsed >= limit) {
    cx.fail(name + ': ' + what + ' must be an integer in 0..' +
        i32ToString(limit - 1) + ', got ' + raw);
  }
  return parsed;
}

/** The wasm value type an instruction leaves on the stack. */
function simdResultVt(result: SimdResult): ValType {
  return match (result) {
  case SimdResult.V128: new ValTypeV128()
  case SimdResult.I32: new ValTypeI32()
  case SimdResult.I64: new ValTypeI64()
  case SimdResult.F32: new ValTypeF32()
  case SimdResult.F64: new ValTypeF64()
  case SimdResult.Void: new ValTypeVoid()
};
}

/** Lowers `count` arguments starting at `from`, in source order. */
function simdOperands(
  cx: LoweringContext,
  call: CallExpression,
  from: i32,
  count: i32
) {
  let out = new Array<i32>(count);
  var i = 0;
  while (i < count) {
    out.push(lowerExpr(cx, call.args[from + i], null));
    i += 1;
  }
  return out;
}

/**
 * One 32-bit word of a `v128.const`. Unlike a lane index this is a
 * VALUE, so the whole i32 range is in bounds — including the negatives,
 * which reach the AST as a negation wrapped around a literal rather
 * than as a literal of their own.
 */
function simdImmediateWord(
  cx: LoweringContext,
  name: String,
  e: Expression
) {
  var negative = false;
  var operand = e;
  match (e) {
    case UnaryExpression as u: {
      if (u.operator == '-') {
        negative = true;
        operand = u.argument;
      }
    }
    case _: {}
  }
  if (!(operand is NumberLiteral)) {
    cx.fail(name + ': every word must be a literal');
  }
  let raw = (operand as NumberLiteral).raw;
  let (ok, parsed) = parseI32WithHex(raw);
  if (!ok) {
    cx.fail(`${name}: ${raw} is not an integer word`);
  }
  return if (negative) 0 - parsed else parsed;
}

/**
 * Every SIMD intrinsic, routed by the operand shape its table row
 * names. The eleven ZIR ops below differ only in where the operands and
 * immediates sit; which of the 236 instructions this is stays a number
 * until emission (see ir.zena's encoding table).
 *
 * Argument order follows the declarations in `zena:simd`, which put
 * each immediate next to the operand it qualifies — `replaceLane(vec,
 * lane, value)` — rather than in wasm's operands-then-immediates order.
 */
function lowerSimd(
  cx: LoweringContext,
  instr: SimdInstruction,
  call: CallExpression
) {
  let {name} = instr;
  if (call.args.length != simdArgCount(instr)) {
    cx.fail(name + ': wrong argument count');
  }
  let resultVt = simdResultVt(instr.result);
  return match (instr.shape) {
    case SimdShape.Unary: {
      let a = lowerExpr(cx, call.args[0], null);
      cx.b.emit(IrOp.simd_unary, resultVt, a, instr.opcode)
    }
    case SimdShape.Binary: {
      let ops = simdOperands(cx, call, 0, 2);
      cx.b.emit(IrOp.simd_binary, resultVt, cx.b.pushExtra(ops), instr.opcode)
    }
    case SimdShape.Ternary: {
      let ops = simdOperands(cx, call, 0, 3);
      cx.b.emit(IrOp.simd_ternary, resultVt, cx.b.pushExtra(ops), instr.opcode)
    }
    case SimdShape.ExtractLane: {
      let vec = lowerExpr(cx, call.args[0], null);
      let lane = simdImmediate(cx, name, 'lane index', call.args[1],
          simdLaneCount(instr));
      cx.b.emit(IrOp.simd_extract_lane, resultVt, vec,
          cx.b.pushExtra(twoValues(instr.opcode, lane)))
    }
    case SimdShape.ReplaceLane: {
      let vec = lowerExpr(cx, call.args[0], null);
      let lane = simdImmediate(cx, name, 'lane index', call.args[1],
          simdLaneCount(instr));
      let value = lowerExpr(cx, call.args[2], null);
      cx.b.emit(IrOp.simd_replace_lane, resultVt,
          cx.b.pushExtra(twoValues(vec, value)),
          cx.b.pushExtra(twoValues(instr.opcode, lane)))
    }
    case SimdShape.Load: {
      let addr = lowerExpr(cx, call.args[0], null);
      cx.b.emit(IrOp.simd_load, resultVt, addr,
          cx.b.pushExtra(twoValues(instr.opcode, instr.align)))
    }
    case SimdShape.Store: {
      let ops = simdOperands(cx, call, 0, 2);
      cx.b.emitVoid(IrOp.simd_store, cx.b.pushExtra(ops),
          cx.b.pushExtra(twoValues(instr.opcode, instr.align)))
    }
    case SimdShape.LoadLane: {
      let ops = simdOperands(cx, call, 0, 2);
      let lane = simdImmediate(cx, name, 'lane index', call.args[2],
          simdLaneCount(instr));
      cx.b.emit(IrOp.simd_load_lane, resultVt, cx.b.pushExtra(ops),
          cx.b.pushExtra(threeValues(instr.opcode, instr.align, lane)))
    }
    case SimdShape.StoreLane: {
      let ops = simdOperands(cx, call, 0, 2);
      let lane = simdImmediate(cx, name, 'lane index', call.args[2],
          simdLaneCount(instr));
      cx.b.emitVoid(IrOp.simd_store_lane, cx.b.pushExtra(ops),
          cx.b.pushExtra(threeValues(instr.opcode, instr.align, lane)))
    }
    case SimdShape.Const: {
      // Four i32 literals, little-endian, into the sixteen immediate
      // bytes — the same order `v128.const i32x4 a b c d` writes them.
      let imm = growable<i32>([instr.opcode]);
      var w = 0;
      while (w < 4) {
        let word = simdImmediateWord(cx, name, call.args[w]);
        var byte = 0;
        while (byte < 4) {
          imm.push((word >> (byte * 8)) & 0xFF);
          byte += 1;
        }
        w += 1;
      }
      cx.b.emit(IrOp.simd_const, resultVt, -1, cx.b.pushExtra(imm))
    }
    case SimdShape.Shuffle: {
      let ops = simdOperands(cx, call, 0, 2);
      let imm = growable<i32>([instr.opcode]);
      var i = 0;
      while (i < 16) {
        // Selectors index the two operands end to end, so they run to 31.
        imm.push(simdImmediate(cx, name, 'lane selector', call.args[2 + i], 32));
        i += 1;
      }
      cx.b.emit(IrOp.simd_shuffle, resultVt, cx.b.pushExtra(ops),
          cx.b.pushExtra(imm))
    }
  };
}

/**
 * The single name -> lowering router for call-position intrinsics.
 * Array-builtin notes: the __byte_array_* variants differ only in
 * element width — packed i8 elements read unsigned (array.get_u) and
 * write plain i32 values. Each lowering checks the element width it
 * requires, so a plain builtin on a packed array (or vice versa) is a
 * lowering bug surfaced as a loud bail, exactly where streaming would
 * emit invalid wasm. Identical-implementation pairs share a function:
 * both length builtins are the width-agnostic array.len, and
 * __array_new_empty / __byte_array_new are both array.new_default.
 */
function lowerToStringIntrinsic(cx: LoweringContext, call: CallExpression) {
  if (call.args.length != 1) {
    cx.fail('to_string arity');
  }
  let arg = call.args[0];
  let tOpt = cx.substitutedNodeType(arg);
  if (tOpt == null) {
    cx.fail('untyped to_string operand');
  }
  let value = lowerExpr(cx, arg, null);
  let res = convertValueToString(cx, value, tOpt, arg.loc);
  return cx.reassertNonNull(res, cx.exprVt(call));
}

export function lowerIntrinsic(cx: LoweringContext, name: String, call: CallExpression, multiOut: GrowableArray<i32> | null): i32 {
  if (isWideArithIntrinsic(name)) {
    if (multiOut == null) {
      // `inline (u64, u64)` has no single wasm value type, so there is
      // no result to hand back here. The destructuring form is the
      // only one that can consume this.
      cx.failValue(name + ': result must be destructured');
    }
    lowerWideArith(cx, name, call, multiOut as GrowableArray<i32>);
    return -1;
  }
  return match (name) {
    case '__array_len': lowerArrayLen(cx, call)
    case '__byte_array_length': lowerArrayLen(cx, call)
    case '__array_get': lowerArrayGet(cx, call)
    case '__byte_array_get': lowerByteArrayGet(cx, call)
    case '__array_set': lowerArraySet(cx, call)
    case '__byte_array_set': lowerByteArraySet(cx, call)
    case '__array_new': lowerArrayNew(cx, call)
    case '__array_new_empty': lowerArrayNewDefault(cx, call)
    case '__byte_array_new': lowerArrayNewDefault(cx, call)
    case '__byte_array_copy': lowerByteArrayCopy(cx, call)
    case 'i32.div_s': lowerInstr(cx, call, IrOp.i32_div_s, new ValTypeI32())
    case 'i32.div_u': lowerInstr(cx, call, IrOp.i32_div_u, new ValTypeI32())
    case 'i64.div_s': lowerInstr(cx, call, IrOp.i64_div_s, new ValTypeI64())
    case 'i64.div_u': lowerInstr(cx, call, IrOp.i64_div_u, new ValTypeI64())
    case 'i64.reinterpret_f64': lowerInstr(cx, call, IrOp.i64_reinterpret_f64, new ValTypeI64())
    case 'i32.clz': lowerInstr(cx, call, IrOp.i32_clz, new ValTypeI32())
    case 'i32.ctz': lowerInstr(cx, call, IrOp.i32_ctz, new ValTypeI32())
    case 'i32.popcnt': lowerInstr(cx, call, IrOp.i32_popcnt, new ValTypeI32())
    case 'i64.clz': lowerInstr(cx, call, IrOp.i64_clz, new ValTypeI64())
    case 'i64.ctz': lowerInstr(cx, call, IrOp.i64_ctz, new ValTypeI64())
    case 'i64.popcnt': lowerInstr(cx, call, IrOp.i64_popcnt, new ValTypeI64())
    case 'i32.reinterpret_f32': lowerInstr(cx, call, IrOp.i32_reinterpret_f32, new ValTypeI32())
    case 'f32.reinterpret_i32': lowerInstr(cx, call, IrOp.f32_reinterpret_i32, new ValTypeF32())
    case 'f64.reinterpret_i64': lowerInstr(cx, call, IrOp.f64_reinterpret_i64, new ValTypeF64())
    case 'i32.trunc_sat_f32_s': lowerInstr(cx, call, IrOp.i32_trunc_sat_f32_s, new ValTypeI32())
    case 'i32.trunc_sat_f32_u': lowerInstr(cx, call, IrOp.i32_trunc_sat_f32_u, new ValTypeI32())
    case 'i32.trunc_sat_f64_s': lowerInstr(cx, call, IrOp.i32_trunc_sat_f64_s, new ValTypeI32())
    case 'i32.trunc_sat_f64_u': lowerInstr(cx, call, IrOp.i32_trunc_sat_f64_u, new ValTypeI32())
    case 'i64.trunc_sat_f32_s': lowerInstr(cx, call, IrOp.i64_trunc_sat_f32_s, new ValTypeI64())
    case 'i64.trunc_sat_f32_u': lowerInstr(cx, call, IrOp.i64_trunc_sat_f32_u, new ValTypeI64())
    case 'i64.trunc_sat_f64_s': lowerInstr(cx, call, IrOp.i64_trunc_sat_f64_s, new ValTypeI64())
    case 'i64.trunc_sat_f64_u': lowerInstr(cx, call, IrOp.i64_trunc_sat_f64_u, new ValTypeI64())
    case 'f32.abs': lowerInstr(cx, call, IrOp.f32_abs, new ValTypeF32())
    case 'f32.ceil': lowerInstr(cx, call, IrOp.f32_ceil, new ValTypeF32())
    case 'f32.floor': lowerInstr(cx, call, IrOp.f32_floor, new ValTypeF32())
    case 'f32.nearest': lowerInstr(cx, call, IrOp.f32_nearest, new ValTypeF32())
    case 'f32.sqrt': lowerInstr(cx, call, IrOp.f32_sqrt, new ValTypeF32())
    case 'f32.trunc': lowerInstr(cx, call, IrOp.f32_trunc, new ValTypeF32())
    case 'f32.neg': lowerInstr(cx, call, IrOp.f32_neg, new ValTypeF32())
    case 'f64.abs': lowerInstr(cx, call, IrOp.f64_abs, new ValTypeF64())
    case 'f64.ceil': lowerInstr(cx, call, IrOp.f64_ceil, new ValTypeF64())
    case 'f64.floor': lowerInstr(cx, call, IrOp.f64_floor, new ValTypeF64())
    case 'f64.nearest': lowerInstr(cx, call, IrOp.f64_nearest, new ValTypeF64())
    case 'f64.sqrt': lowerInstr(cx, call, IrOp.f64_sqrt, new ValTypeF64())
    case 'f64.trunc': lowerInstr(cx, call, IrOp.f64_trunc, new ValTypeF64())
    case 'f64.neg': lowerInstr(cx, call, IrOp.f64_neg, new ValTypeF64())
    case 'f32.min': lowerInstr(cx, call, IrOp.f32_min, new ValTypeF32())
    case 'f32.max': lowerInstr(cx, call, IrOp.f32_max, new ValTypeF32())
    case 'f32.copysign': lowerInstr(cx, call, IrOp.f32_copysign, new ValTypeF32())
    case 'f64.min': lowerInstr(cx, call, IrOp.f64_min, new ValTypeF64())
    case 'f64.max': lowerInstr(cx, call, IrOp.f64_max, new ValTypeF64())
    case 'f64.copysign': lowerInstr(cx, call, IrOp.f64_copysign, new ValTypeF64())
    case 'i32.load': lowerMemLoad(cx, call, IrOp.i32_load, new ValTypeI32(), 2)
    case 'i32.load8_u': lowerMemLoad(cx, call, IrOp.i32_load8_u, new ValTypeI32(), 0)
    case 'i64.load': lowerMemLoad(cx, call, IrOp.i64_load, new ValTypeI64(), 3)
    case 'f32.load': lowerMemLoad(cx, call, IrOp.f32_load, new ValTypeF32(), 2)
    case 'f64.load': lowerMemLoad(cx, call, IrOp.f64_load, new ValTypeF64(), 3)
    case 'i32.store': lowerMemStore(cx, call, IrOp.i32_store, 0)
    case 'i32.store8': lowerMemStore(cx, call, IrOp.i32_store8, 0)
    case 'i64.store': lowerMemStore(cx, call, IrOp.i64_store, 0)
    case 'f32.store': lowerMemStore(cx, call, IrOp.f32_store, 0)
    case 'f64.store': lowerMemStore(cx, call, IrOp.f64_store, 0)
    case 'memory.size': cx.b.emit(IrOp.memory_size, new ValTypeI32(), -1, -1)
    case 'memory.grow': lowerMemoryGrow(cx, call)
    case 'cancel.raise': lowerCancelRaise(cx, call)
    case 'eq': {
      lowerEqIntrinsic(cx, call)
    }
    case 'hash': {
      lowerHashIntrinsic(cx, call)
    }
    case 'to_string': {
      lowerToStringIntrinsic(cx, call)
    }
    case 'default_value': lowerDefaultValue(cx, call)
    case 'is_first_class': lowerIsFirstClass(cx, call)
    case 'release_owned': lowerReleaseOwned(cx, call)
    case 'share_reference': lowerShareReference(cx, call)
    case _: {
      // SIMD instructions are not listed above: one table row in
      // lib/simd.zena carries the opcode, shape and result for all 236,
      // and the same row is what let the name past the checker.
      let instr = simdInstruction(name);
      if (instr != null) {
        lowerSimd(cx, instr, call)
      } else {
        cx.failValue('intrinsic ' + name)
      }
    }
  };
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19