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

91.3 KiB Raw
/**
 * The single shared surface that split-out lowering modules see.
 * FunctionLowerer cannot be imported by them (import cycle with
 * lowering.zena), so the mutually-recursive core arrives as closures,
 * while the builder, module, and function are direct fields. Every
 * split module shares THIS type — a new module extends it with more
 * closures rather than minting its own context (ir/intrinsics.zena
 * predates this and keeps its narrower IntrinsicCx).
 */
import { Set, HashMap, HashSet } from 'zena:collections';
import {
  AssignmentExpression, BindingPattern, CallExpression, Expression, FunctionExpression, Identifier, IdentifierPattern, IndexExpression, MemberExpression, Node, Statement, VariableDeclaration,
} from '../../ast.zena';
import {
  ClassType, FunctionType, InterfaceType, NullType, RecordType, ThisType, TupleType, Type,
  UnionType, baseType,
} from '../../types.zena';
import {
  ValType, ValTypeAnyRef, ValTypeEqRef, ValTypeF32, ValTypeF64,
  ValTypeI32, ValTypeI64, ValTypeV128, ValTypeRef, ValTypeRefNull,
  ValTypeRefExtern, ValTypeExternRef,
  ValTypeStructRef, ValTypeNullRef, ValTypeVoid, isRefValType, refTargetOf,
} from '../wasm.zena';
import {
  substituteTypeParamsInFunctionContext, typeToValTypeWithSub,
  recordWasmFields, sortedOptionalNames, InlineLayout,
} from '../type-mapping.zena';
import { IrOp } from './ir.zena';
import {
  WasmModule, WasmFunction, WasmSignature, ClassCodegenInfo,
  RecordDispatchInfo, WasmField, WasmGlobal, WasmStruct, asWasmSignature,
  asWasmStruct, isValSubtype,
  valTypeIdentical,
  sortWasmFields, typeTestSlotName, rootStruct, TypeTestCandidate,
} from '../wasm-module.zena';
import { getCellKey, getCellStruct } from '../type-mapping.zena';
import {
  getClassInterfaceKey, getClassKey, getClassMethodKey, getInterfaceKey,
  getSignatureKey, ClassKey, InterfaceKey, unwrapAliases,
} from '../codegen-utils.zena';
import { IrRefField, IrRefFunc, IrRefGlobal, IrRefType } from './ir.zena';
import { IrBuilder } from './builder.zena';
import {
  GuardKind, accessorOverriddenIn, memberProvidedIn, vtableSlotIn, refConformsTo,
  methodOwnerIn,
} from './template.zena';
import { Symbol, SymbolId } from '../../scope/symbol.zena';
import { walkEnter } from '../../visitor.zena';
// Imported back across the module cycle: lowering.zena imports this
// module (docs/design/import-cycles.md).
import { FunctionLowerer, lowerExpr, MultiValues } from './lowering.zena';
import { growable } from 'zena:core';

/**
 * Thrown when lowering meets a construct it does not model; the
 * compile fails with the offending function named (see lowerFunction).
 * States the checker guarantees impossible are NOT ZirUnsupported —
 * throw a plain Error for those. (Defined here rather than in
 * lowering.zena so split modules can throw it without an import
 * cycle.)
 */
export final class ZirUnsupported extends Error {
  new(reason: String) : super('zir unsupported: ' + reason);
}

/** One loop's break/continue targets and carried symbols. */
export final class LoopCtx {
  /** Where `continue` jumps: the header for while, the update block for for. */
  continueTarget: i32;
  exit: i32;
  carried: GrowableArray<SymbolId>;
  new(this.continueTarget, this.exit, this.carried);
}

/**
 * A `try` region with a finalizer, while its protected part lowers.
 *
 * The finalizer is emitted ONCE, in `dispatch`, which every way out of
 * the region reaches: normal completion, the region's handler edge,
 * and each `return`/`break`/`continue` that leaves it. `codeVar` says
 * which — the dispatch replays it after the finalizer has run (see
 * `lowerTryFinally`). Innermost scope last; an exit replayed at one
 * dispatch re-enters this list truncated, so nested finalizers run
 * inside-out with no duplicated code.
 */
export final class FinallyScope {
  /** The block holding the finalizer and the exit replay. */
  dispatch: i32;
  /** Holds a `finallyExit*` code: which exit the dispatch must replay. */
  codeVar: i32;
  /**
   * `cx.loops.length` on entry. A `break`/`continue` whose target loop
   * was opened before that leaves this region and owes the finalizer;
   * one opened inside the region does not.
   */
  loopDepth: i32;
  /** Holds the returned value; allocated by the first `return` out. */
  var returnVar = -1;
  /** One variable per result for a MULTI-VALUE return out — the same
   * parking, one var per slot. Exclusive with returnVar: a function's
   * signature is either single- or multi-result. */
  var returnVars: GrowableArray<i32> | null = null;
  /** False when nothing completes the protected part normally (every
   * path threw or left) — then the try has no continuation at all. */
  var exitsNormally = false;
  var exitsByReturn = false;
  var exitsByBreak = false;
  var exitsByContinue = false;
  new(this.dispatch, this.codeVar, this.loopDepth);
}

/**
 * The lazily-materialized join point of a value-producing control-flow
 * expression (if/try/match) or a merging statement. Arms br to it with
 * the tracked symbols' current values (plus the arm's result in value
 * position); it exists only once some arm actually reaches it.
 */
export final class MergeState {
  syms: GrowableArray<SymbolId>;
  isVoid: boolean;
  resultVt: ValType | null;
  var block = -1;
  var params: GrowableArray<i32> | null = null;
  var resultParam = -1;
  /**
   * Set when the merged value is a record a core returns as its fields:
   * the arms pass the fields (mergeArmFields), one parameter each, in
   * place of the record.
   */
  var fields: RecordDispatchInfo | null = null;
  var fieldParams: GrowableArray<i32> | null = null;
  /**
   * Set when the expression is a returned inline value: each arm
   * returns its own value (`returnInlineTail`), so no arm reaches the
   * merge with one.
   */
  var returnTail = false;
  /**
   * Set when the merged value is an inline value held in slots: the
   * arms pass their slots (mergeArmSlots), one parameter each.
   */
  var slots: ResultSlots | null = null;
  var slotParams: GrowableArray<i32> | null = null;
  new(this.syms, this.isVoid, this.resultVt);
}

/**
 * The slots an inline `if` or `match` is lowered into, in a `let` or as
 * an argument (docs/design/inline-parameters.md): `slotVts` of the
 * inline layout `layout`, null for a positional multi-value.
 */
export final class ResultSlots {
  layout: InlineLayout | null;
  slotVts: GrowableArray<ValType>;
  new(this.layout, this.slotVts);
}

/** A lowered let-condition: the flag plus bindings to apply in the
 * SUCCESS block only — coercing an exhausted iterator's null payload
 * would trap if emitted before the flag branch. */
export final class LetCondBinds {
  cond: i32;
  syms: GrowableArray<Symbol>;
  values: GrowableArray<i32>;
  vts: GrowableArray<ValType>;
  /** Nested destructuring elements, tested/bound in the taken block. */
  patterns: GrowableArray<Node>;
  patternValues: GrowableArray<i32>;
  /**
   * The source when it holds an owner: the pattern consumes it, so the
   * not-taken side releases it whole and the taken side releases the
   * owners no name took (`ownerKept` holds the paths the pattern bound,
   * for the members `ownerAllowed` keeps).
   */
  var ownerSource: MultiValues | null = null;
  var ownerAllowed: GrowableArray<boolean> | null = null;
  var ownerKept: HashSet<String> | null = null;
  new(this.cond, this.syms, this.values, this.vts, this.patterns,
      this.patternValues);
}

/**
 * An exploded parameter's record, rebuilt on entry to the core, and the
 * field values it was built from, in `dispatch.fields` order.
 */
export final class ExplodedRecord {
  dispatch: RecordDispatchInfo;
  values: GrowableArray<i32>;
  new(this.dispatch, this.values);
}

/**
 * How an inline `var` crosses a join (#813, docs/design/inline-parameters.md):
 * as its slots, one block parameter of `slotTypes` each. `slotsOf` reads
 * the slots of the env entry the var has, `bind` makes an env entry from
 * slots, and `write` lowers a value written to the var (its initializer
 * or an assignment) to an env entry.
 */
export final class InlineVar {
  slotTypes: GrowableArray<ValType>;
  slotsOf: (entry: i32) => GrowableArray<i32>;
  bind: (slots: GrowableArray<i32>) => i32;
  write: (value: Expression) => i32;
  new(this.slotTypes, this.slotsOf, this.bind, this.write);
}

export final class LoweringContext {
  b: IrBuilder;
  wasm: WasmModule;
  func: WasmFunction;
  // ---- Mutable per-function lowering state (single-homed HERE; the
  // coordinator and every split module read and write the same
  // instance). SSA construction is the structured-AST form: `env`
  // maps each variable symbol to its current value.
  var env = new Map<SymbolId, i32>();
  /**
   * While a host constructor lowers a field decorator's initializers:
   * the application (the intermediate class) they belong to, which is
   * what `context` in such an initializer refers to. A decorator's
   * method or accessor body reads its application from
   * `func.declaringType` instead.
   */
  var decoratorApplication: ClassType | null = null;
  /** Symbols behind env entries, for binding-type lookups at merges. */
  symbols = new Map<SymbolId, Symbol>();
  /**
   * In an exploded core (ExplosionSpec), the record rebuilt on entry
   * for each exploded parameter, keyed by that record's value id, to
   * the field values it was built from.
   * `recordDispatchRead` answers a read off one of these records with
   * the field value, so the rebuilt record has no uses and DCE deletes
   * it.
   */
  explodedRecords = new Map<i32, ExplodedRecord>();

  /**
   * An inline parameter or `let`'s slots, by its symbol
   * (docs/design/inline-parameters.md). Its env entry is NO_VALUE: every
   * reader that takes a multi-value source reads these, and a use that
   * needs one value boxes them.
   */
  inlineBindings = new Map<SymbolId, MultiValues>();
  /**
   * How each inline `var` crosses a join (#813). Its env entry changes
   * with every write, and the env is saved and restored around every
   * branch, so the entry itself carries the current value: a record
   * held as its fields, or, for slots, `holdSlots`'s handle on one of
   * `#slotStates`.
   */
  inlineVars = new Map<SymbolId, InlineVar>();
  #slotStates = new Array<MultiValues>();

  /**
   * An env entry for an inline var holding `slots`: a handle below -1
   * (lowering.zena's NO_VALUE), so it is never taken for a value id. A
   * state is never changed after it is recorded, so a restored env sees
   * the slots it saw when it was saved.
   */
  holdSlots(slots: MultiValues): i32 {
    this.#slotStates.push(slots);
    return -1 - this.#slotStates.length;
  }

  /** The slots a `holdSlots` handle stands for. */
  heldSlots(handle: i32): MultiValues {
    let index = -2 - handle;
    if (index < 0 || index >= this.#slotStates.length) {
      this.fail('inline var handle');
    }
    return this.#slotStates[index];
  }

  loops = new Array<LoopCtx>();
  /** Enclosing scopes whose normal-exit drops run before `returnInlineTail` returns. */
  tailExitScopes = new Array<Node>();
  /** Values piped by enclosing |> expressions; $ reads the top. */
  pipelineValues = new Array<i32>();
  /**
   * Values known to be EXACTLY their class (freshly constructed by
   * struct.new in this function, or a singleton global). A method
   * call on an exact receiver never needs the vtable, even when
   * subclasses override the slot — no subclass instance can be here.
   * Merges, cells, and casts produce new ids, so exactness is
   * conservatively local.
   */
  exactValues = new Set<i32>();
  var reachable = true;
  /** The receiver value for instance methods; -1 elsewhere. */
  var thisValue = -1;
  /**
   * The owning FunctionLowerer (the coordinator in lowering.zena,
   * named here across the import cycle's back edge). Assigned when
   * the coordinator builds its context.
   */
  var host: FunctionLowerer | null = null;

  new(this.b, this.wasm, this.func);

  /**
   * ZIR's conformance gate: isValSubtype, EXCEPT nullable never
   * conforms to non-null. The shared isValSubtype inherits streaming's
   * nullability-loose valTypeEquals shortcut (streaming declares ref
   * locals nullable and re-casts at uses); ZIR types values exactly,
   * so the loose shortcut would silently skip required narrowing.
   */
  refConforms(have: ValType, want: ValType): boolean {
    return refConformsTo(have, want);
  }

  /**
   * Throws ZirUnsupported. Declared `never`, so a statement-position
   * `cx.fail(...)` counts as a path exit for the checker: guards like
   * `if (x == null) { cx.fail('...'); }` narrow `x` afterward, the same
   * way an inline `throw` would.
   */
  fail(reason: String): never {
    throw new ZirUnsupported(`${reason} @${this.func.name ?? '?'}`);
  }

  /** The storage ValType of an already-lowered value. */
  valueTypeOf(value: i32): ValType {
    return this.b.body.typeTable[this.b.body.typeId[value]];
  }

  /**
   * Re-asserts non-nullness when the checked type is non-null but the
   * value's storage type is nullable with the same heap target. Other
   * shape differences pass through unchanged — downstream subtype
   * checks bail on actual misuse.
   */
  reassertNonNull(value: i32, want: ValType): i32 {
    let have = this.valueTypeOf(value);
    if (want is ValTypeRef && have is ValTypeRefNull &&
        want.target == have.target) {
      return this.b.emit(IrOp.ref_as_non_null, want, value, -1);
    }
    if (want is ValTypeRefExtern && have is ValTypeExternRef) {
      return this.b.emit(IrOp.ref_as_non_null, want, value, -1);
    }
    return value;
  }

  /** ref.as_non_null when the value's own storage type is nullable. */
  stripNonNull(value: i32): i32 {
    let vt = this.valueTypeOf(value);
    return if (vt is ValTypeRefNull) {
      this.reassertNonNull(
          value, new ValTypeRef(vt.target) as ValType)
    } else if (vt is ValTypeExternRef) {
      this.reassertNonNull(
          value, new ValTypeRefExtern() as ValType)
    } else {
      value
    };
  }

  /**
   * `fail` for spots that must sit in an i32 value position (match arms
   * producing a value id): the i32 never arrives, but a bare
   * never-typed call cannot be a value arm yet (elematic/zena#79).
   */
  failValue(reason: String): i32 {
    this.fail(reason);
  }

  /** Types values may HAVE in the lowered subset (see lowering docs). */
  requireSupported(vt: ValType, what: String): void {
    let ok = vt is ValTypeI32 || vt is ValTypeI64 || vt is ValTypeF32 ||
        vt is ValTypeF64 || vt is ValTypeV128 || vt is ValTypeRef ||
        vt is ValTypeRefNull || vt is ValTypeNullRef ||
        vt is ValTypeRefExtern || vt is ValTypeExternRef ||
        vt is ValTypeAnyRef || vt is ValTypeEqRef || vt is ValTypeStructRef;
    if (!ok) {
      this.fail(what);
    }
  }

  /** The expression's own checked type, substituted and supported. */
  exprVt(expr: Expression): ValType {
    let t = this.func.model.getNodeType(expr);
    if (t == null) {
      this.fail('untyped expression');
    }
    let vt = typeToValTypeWithSub(this.wasm, t, this.func);
    this.requireSupported(vt, 'expression type');
    return vt;
  }

  /**
   * A binding's declared type, substituted for the specialization being
   * lowered: an owned parameter or receiver of a generic class method
   * names the class at its own type parameters.
   */
  bindingTypeOf(id: SymbolId): Type | null {
    let t = this.func.model.getBindingTypeById(id);
    if (t == null) {
      return null;
    }
    return substituteTypeParamsInFunctionContext(this.wasm, this.func, t);
  }

  /** The checked semantic type, substituted; null when untyped. */
  substitutedNodeType(expr: Node): Type | null {
    let t = this.func.model.getNodeType(expr);
    if (t == null) {
      return null;
    }
    return substituteTypeParamsInFunctionContext(this.wasm, this.func, t);
  }

  /**
   * Value-conformance failure: a lowered value does not satisfy the
   * type its consumer requires. A scalar flowing into an any/eqref
   * context would need auto-boxing, which ZIR deliberately does not
   * implement — that case bails under its own permanent name so the
   * histogram tracks it.
   */
  failConformance(value: i32, want: ValType, reason: String): void {
    let vt = this.valueTypeOf(value);
    if (!isRefValType(vt) &&
        (want is ValTypeAnyRef || want is ValTypeEqRef)) {
      this.fail('auto-box to any');
    }
    this.fail(reason);
  }

  /** Packs a class instance value into `it`'s fat pointer. */
  packInterface(value: i32, ct: ClassType, it: InterfaceType): i32 {
    let iName = getInterfaceKey(it);
    let key = getClassInterfaceKey(getClassKey(ct), iName);
    let vtOpt = this.wasm.getClassInterfaceVTable(key);
    if (vtOpt == null) {
      this.fail(`interface vtable global not found: ${key.classKey as String} as ${key.interfaceKey as String}`);
    }
    let fatPtrOpt = if (let (true, st) = this.wasm.interfaceStructs.get(iName)) st else null;
    if (fatPtrOpt == null) {
      this.fail('interface struct not found');
    }
    let fatPtr = fatPtrOpt;
    let globalRef = this.b.addRef(new IrRefGlobal(vtOpt));
    return this.b.emit(IrOp.iface_pack, new ValTypeRef(fatPtr) as ValType,
        value, globalRef);
  }

  /** Repacks a sub-interface fat pointer value into `tgtIt`'s fat pointer. */
  repackInterface(value: i32, srcIt: InterfaceType, tgtIt: InterfaceType): i32 {
    return repackInterfaceValue(this.wasm, this.b, value,
        getInterfaceKey(srcIt), getInterfaceKey(tgtIt));
  }

  /**
   * Maps ThisType (and the checker's `<Name>_This` marker classes) to
   * the enclosing method's concrete class.
   */
  resolveSelfType(t: Type): Type {
    let bt = baseType(t);
    var isSelf = bt is ThisType;
    if (!isSelf && bt is ClassType) {
      if (bt.name.length >= 5 &&
          bt.name.sliceBytes(bt.name.length - 5, bt.name.length) == "_This") {
        isSelf = true;
      }
    }
    if (isSelf) {
      if (this.func.classType == null) {
        this.fail('self type outside method');
      }
      return this.func.classType as Type;
    }
    return bt;
  }

  /**
   * Dispatches a receiver-only interface method through the vtable of
   * an already-lowered fat-pointer VALUE. The fat pointer's own struct
   * type names the vtable struct, so no InterfaceType resolution is
   * needed past whatever produced the value — the :iterator slot's
   * signature hands the loop the Iterator fat-pointer type for free.
   * Returns the call's result values (empty for void).
   */
  slotCallOnValue(recv: i32, memberName: String): GrowableArray<i32> {
    let fatOpt = asWasmStruct(this.valueTypeOf(recv));
    if (fatOpt == null || fatOpt.fields.length != 2) {
      this.fail('interface receiver type');
    }
    let fatPtr = fatOpt;
    let vstOpt = asWasmStruct(fatPtr.fields[1].type);
    if (vstOpt == null) {
      this.fail('interface receiver type');
    }
    let vst = vstOpt;
    let slot = vst.fieldIndexByName(memberName);
    if (slot < 0) {
      this.fail(`interface member not in vtable: ${memberName}`);
    }
    let sigOpt = asWasmSignature(vst.fields[slot].type);
    if (sigOpt == null) {
      this.fail('interface slot shape');
    }
    let sig = sigOpt;
    if (sig.params.length != 1) {
      this.fail('interface call arity adaptation');
    }
    let inst = this.b.emit(
        IrOp.iface_instance, fatPtr.fields[0].type, recv, -1);
    if (!isValSubtype(this.valueTypeOf(inst), sig.params[0])) {
      this.failConformance(inst, sig.params[0], 'interface receiver adaptation');
    }
    let vt = this.b.emit(IrOp.iface_vtable, fatPtr.fields[1].type, recv, -1);
    let fieldRef = this.b.addRef(new IrRefField(vst, memberName));
    let callee = this.b.emit(
        IrOp.struct_get, vst.fields[slot].type, vt, fieldRef);
    for (let r in sig.returns) {
      this.requireSupported(r, 'interface result type');
    }
    let args = oneValue(inst);
    if (sig.returns.length > 1) {
      return this.b.callRefMulti(callee, args, sig.returns);
    }
    let resultType = if (sig.returns.length == 1) sig.returns[0] else null;
    let result = this.b.callRef(callee, args, resultType);
    let out = new Array<i32>();
    if (resultType != null) {
      out.push(result);
    }
    return out;
  }

  /** #slotCallOnValue for members returning exactly one value. */
  slotCallSingle(recv: i32, memberName: String): i32 {
    let results = this.slotCallOnValue(recv, memberName);
    if (results.length != 1) {
      this.fail('interface slot shape');
    }
    return results[0];
  }

  /** #slotCallOnValue for members with multi-value returns. */
  slotCallMulti(recv: i32, memberName: String): GrowableArray<i32> {
    return this.slotCallOnValue(recv, memberName);
  }

  /**
   * The receiver of an optional chain, WITHOUT the checked-type
   * re-assert: the checker narrows the receiver non-null at the
   * access node (it must be accessible to type the chain), but the
   * whole point of `?.` is that the runtime value may be null — the
   * re-assert would trap before the null test. Identifier and
   * global receivers read raw; other expressions produce their own
   * (nullable) values.
   */
  chainReceiver(obj: Expression): i32 {
    if (obj is Identifier) {
      let sym = this.func.model.resolve(obj);
      if (sym != null) {
        let resolved = sym.resolveTarget();
        if (this.env.has(resolved.id)) {
          var value = this.env[resolved.id];
          if (this.isCelled(resolved.id)) {
            value = this.cellRead(value);
          }
          return value;
        }
        if (let (true, g) = this.wasm.globalMap.get(resolved.id)) {
          let globalRef = this.b.addRef(new IrRefGlobal(g));
          return this.b.emit(IrOp.global_get, g.type, -1, globalRef);
        }
      }
    }
    return lowerExpr(this, obj, null);
  }

  /**
   * The ClassType a lowered receiver value actually carries: struct
   * types remember their class. This beats re-deriving the class from
   * checked node types, which name the GENERIC class inside
   * specialized-method bodies (same authoritative-source principle as
   * the closure-identity fix).
   */
  classTypeOfValue(value: i32): ClassType | null {
    let st = asWasmStruct(this.valueTypeOf(value));
    if (st != null) {
      return st.classType;
    }
    return null;
  }

  /** The generic-source root's key: specializations compare equal to
   * their template through this. */
  canonicalKeyOf(ct: ClassType): String {
    var c = ct;
    while (c.genericSource != null) {
      c = c.genericSource as ClassType;
    }
    return getClassKey(c) as String;
  }

  /** Resolves a method on ct (walking supers/generic sources) only
   * when no transitive subclass overrides it: a direct call stands
   * in for virtual dispatch. */
  resolveDevirtualizedMethod(ct: ClassType, methName: String): WasmFunction | null {
    // Which class in the chain provides the method is a fact about the
    // class `ct` is, which a type parameter can stand for: template mode
    // records it.
    let owner = methodOwnerIn(this.wasm, ct, methName);
    let recorder = this.b.recorder;
    if (recorder != null) {
      recorder.noteMethodOwner(ct, methName, owner);
    }
    if (owner.length == 0) {
      return null;
    }
    let found = this.wasm.classMethodMap[getClassMethodKey(owner as ClassKey, methName)];
    var infoOpt: ClassCodegenInfo | null = null;
    if (let (true, info) = this.wasm.classInfos.get(getClassKey(ct))) {
      infoOpt = info;
    }
    if (infoOpt != null &&
        this.memberProvidedBySubclass(infoOpt, methName)) {
      return null;
    }
    return found;
  }

  /**
   * True if a transitive subclass provides an accessor for `slotName`
   * that actually differs from a direct field read.
   *
   * Every class carrying a physical field gets a *synthesized* default
   * accessor — a `ref.cast` plus `struct.get` on its own struct. A
   * subclass that merely inherits the field therefore has a `get#x`
   * entry of its own, and `memberProvidedBySubclass` counts it, which
   * forced `obj.field` to dispatch through the vtable on every read
   * whenever the receiver's class had any subclass at all. That cost
   * ~59x on the FieldAccessVirtual benchmark against a direct
   * `struct.get`.
   *
   * A synthesized accessor for the *same* field is not an override:
   * wasm-gc struct subtyping puts the inherited field at the same
   * index, so reading it off the receiver's struct is exactly what the
   * subclass accessor would have done. Only a hand-written accessor,
   * or a synthesized one bound to a different field, needs dispatch.
   */
  accessorOverriddenBySubclass(classInfo: ClassCodegenInfo, slotName: String,
      fieldName: String): boolean {
    // The rule (accessorOverriddenIn): a hand-written accessor, or a
    // synthesized one bound to a different field or a different slot,
    // is an override. A synthesized accessor for the same field at the
    // same index (wasm-gc subtyping keeps inherited fields at their
    // supertype index) reads exactly what a direct read would.
    let answer = accessorOverriddenIn(this.wasm, classInfo, slotName, fieldName);
    let recorder = this.b.recorder;
    if (recorder != null) {
      recorder.note(GuardKind.AccessorOverridden, classInfo, slotName, fieldName,
          if (answer) 1 else 0);
    }
    return answer;
  }

  /** True if any transitive subclass provides its own `methodName`. */
  memberProvidedBySubclass(classInfo: ClassCodegenInfo, methodName: String): boolean {
    let answer = memberProvidedIn(this.wasm, classInfo, methodName);
    let recorder = this.b.recorder;
    if (recorder != null) {
      recorder.note(GuardKind.MemberProvided, classInfo, methodName, '',
          if (answer) 1 else 0);
    }
    return answer;
  }

  /**
   * Whether the receiver class's vtable struct carries `slotName` —
   * the precondition for virtual dispatch through it.
   */
  vtableSlotIndex(classInfo: ClassCodegenInfo, slotName: String): i32 {
    let answer = vtableSlotIn(classInfo, slotName);
    let recorder = this.b.recorder;
    if (recorder != null) {
      recorder.note(GuardKind.VTableSlot, classInfo, slotName, '', answer);
    }
    return answer;
  }

  /**
   * Virtual dispatch through the class vtable: load the receiver's
   * `<vtable>` field, cast to the class's vtable struct, load the
   * named slot, cast to the resolved method's exact signature, and
   * call_ref — streaming's shape. The slot signature is the STATIC
   * class's resolved method signature; overrides conform to it via
   * the vtable-init adapters.
   */
  lowerVtableCall(receiver: i32, classInfo: ClassCodegenInfo,
      slotName: String, sig: WasmSignature, args: GrowableArray<i32>,
      resultType: ValType | null): i32 {
    let slot = this.vtableSlotCallee(receiver, classInfo, slotName, sig);
    return this.b.callRef(slot, args, resultType);
  }

  /** lowerVtableCall for multi-value slot signatures: same slot load,
   * callRefMulti's projection contract. */
  lowerVtableCallMulti(receiver: i32, classInfo: ClassCodegenInfo,
      slotName: String, sig: WasmSignature, args: GrowableArray<i32>): GrowableArray<i32> {
    let slot = this.vtableSlotCallee(receiver, classInfo, slotName, sig);
    return this.b.callRefMulti(slot, args, sig.returns);
  }

  /** The vtable slot of an already-lowered receiver, cast to the
   * resolved method's exact signature — the callee value for call_ref. */
  vtableSlotCallee(receiver: i32, classInfo: ClassCodegenInfo,
      slotName: String, sig: WasmSignature): i32 {
    let {structType} = classInfo;
    let vtStruct = classInfo.vtableStructType as WasmStruct;
    let vtFieldVt = this.fieldValType(structType, '<vtable>');
    let vtRaw = this.b.emit(IrOp.struct_get, vtFieldVt, receiver,
        this.b.addRef(new IrRefField(structType, '<vtable>')));
    var vt = vtRaw;
    let wantVtVt: ValType = new ValTypeRef(vtStruct);
    if (!isValSubtype(this.valueTypeOf(vtRaw), new ValTypeRefNull(vtStruct) as ValType)) {
      vt = this.b.emit(IrOp.ref_cast, wantVtVt, vtRaw,
          this.b.internType(wantVtVt));
    } else {
      vt = this.reassertNonNull(vtRaw, wantVtVt);
    }
    let slotVt = this.fieldValType(vtStruct, slotName);
    let slotRaw = this.b.emit(IrOp.struct_get, slotVt, vt,
        this.b.addRef(new IrRefField(vtStruct, slotName)));
    let sigVt: ValType = new ValTypeRef(sig);
    return this.b.emit(IrOp.ref_cast, sigVt, slotRaw,
        this.b.internType(sigVt));
  }

  fieldValType(owner: WasmStruct, name: String): ValType {
    let idx = owner.fieldIndexByName(name);
    if (idx < 0) {
      this.fail('field not found on struct');
    }
    return owner.fields[idx].type;
  }

  /** A record property read through an already-known dispatch. */
  recordDispatchRead(dispatch: RecordDispatchInfo, propName: String,
      receiver: i32): i32 {
    var fieldIdx = -1;
    for (var i = 0; i < dispatch.fields.length; i += 1) {
      let f = dispatch.fields[i];
      if (f.name != null && (f.name as String) == propName) {
        fieldIdx = i;
      }
    }
    if (fieldIdx < 0) {
      this.fail('record member not found');
    }
    if (let (true, exploded) = this.explodedRecords.get(receiver)) {
      if (exploded.dispatch === dispatch) {
        return exploded.values[fieldIdx];
      }
    }
    if (dispatch.isTuple) {
      return this.b.emit(IrOp.struct_get, dispatch.fields[fieldIdx].type, receiver,
          this.b.addRef(new IrRefField(dispatch.concreteType, propName)));
    }
    let recv = this.stripNonNull(receiver);
    let instance = this.b.emit(IrOp.iface_instance,
        new ValTypeStructRef() as ValType, recv, -1);
    let vtable = this.b.emit(IrOp.iface_vtable,
        new ValTypeRef(dispatch.vtableType) as ValType, recv, -1);
    let getterSig = dispatch.getterTypes[fieldIdx];
    if (getterSig.returns.length != 1) {
      this.fail('record getter shape');
    }
    let getter = this.b.emit(IrOp.struct_get,
        new ValTypeRef(getterSig) as ValType, vtable,
        this.b.addRef(new IrRefField(dispatch.vtableType, propName)));
    return this.b.callRef(getter, oneValue(instance), getterSig.returns[0]);
  }

  /**
   * A class field/getter read by name on an already-lowered receiver
   * value: physical field first, else a registered non-static getter
   * up the super chain.
   */
  objectPropertyRead(propName: String, receiver: i32): i32 {
    let stOpt = asWasmStruct(this.valueTypeOf(receiver));
    if (stOpt == null) {
      this.fail('destructuring source kind');
    }
    let st = stOpt;
    if (st.fieldIndexByName(propName) >= 0) {
      let fieldRef = this.b.addRef(new IrRefField(st, propName));
      return this.b.emit(IrOp.struct_get,
          this.fieldValType(st, propName), receiver, fieldRef);
    }
    let ctOpt = this.classTypeOfValue(receiver);
    if (ctOpt == null) {
      this.fail('destructuring source kind');
    }
    var getterOpt: WasmFunction | null = null;
    var currClass: ClassType | null = ctOpt;
    while (currClass != null && getterOpt == null) {
      let key = getClassMethodKey(
          getClassKey(currClass), 'get#' + propName);
      if (let (true, g) = this.wasm.classMethodMap.get(key)) {
        getterOpt = g;
      }
      currClass = currClass.superType;
    }
    if (getterOpt == null || getterOpt.isStatic) {
      this.fail('member not found: get#' + propName);
    }
    let getter = getterOpt;
    let sig = getter.signature;
    if (sig.returns.length != 1) {
      this.fail('getter shape');
    }
    let recv = this.conformReceiver(receiver, sig.params[0],
        'property receiver type');
    return this.b.callFunc(this.b.addRef(new IrRefFunc(getter)),
        oneValue(recv), sig.returns[0]);
  }

  /**
   * The instance behind `value`, when its wasm type IS an interface fat
   * pointer; `value` unchanged otherwise.
   *
   * The sibling below asks the same question of a semantic type. This
   * one asks it of the representation, for the places that have a
   * lowered value and no type to consult — a narrowed identifier read,
   * where the checker's type for the use is already the narrowed class
   * and the stored value is still the pair.
   *
   * A reverse scan rather than a marker on the struct: `interfaceStructs`
   * is the registry that decides what a fat pointer IS, so asking it
   * cannot drift from what packing produced. It runs only on the
   * coercion path, where the types have already failed to match.
   */
  unwrapFatPointerValue(value: i32): i32 {
    let vt = this.valueTypeOf(value);
    let st = asWasmStruct(vt);
    if (st == null) {
      return value;
    }
    for (let pair in this.wasm.interfaceStructs) {
      if (pair.value == st) {
        return this.fatPointerInstance(st, value);
      }
    }
    return value;
  }

  /**
   * Identity compares see through fat pointers: a record or interface
   * value becomes its eq-typed instance (field 0); everything else
   * passes through unchanged.
   */
  unwrapFatPointer(rawBase: Type, value: i32): i32 {
    let base = unwrapAliases(rawBase);
    if (base is RecordType) {
      let dispatch = this.recordDispatchOf(base);
      return this.fatPointerInstance(dispatch.fatPtrType, value);
    }
    if (base is InterfaceType) {
      let iName = getInterfaceKey(base);
      let fatOpt = if (let (true, st) = this.wasm.interfaceStructs.get(iName)) st else null;
      if (fatOpt == null) {
        this.fail('interface struct not found');
      }
      return this.fatPointerInstance(fatOpt, value);
    }
    if (base is UnionType) {
      // A nullable fat pointer (`Shape | null`) unwraps behind a null
      // guard: null stays null and compares like any null reference.
      var nonNull: Type | null = null;
      var nonNullCount = 0;
      var nullCount = 0;
      for (let m in base.types) {
        if (m is NullType) {
          nullCount += 1;
        } else {
          nonNull = m;
          nonNullCount += 1;
        }
      }
      if (nonNullCount != 1 || nullCount == 0) {
        return value;
      }
      let inner = unwrapAliases(nonNull as Type);
      var fatOpt: WasmStruct | null = null;
      if (inner is RecordType) {
        fatOpt = this.recordDispatchOf(inner).fatPtrType;
      } else if (inner is InterfaceType) {
        let iName = getInterfaceKey(inner);
        if (let (true, st) = this.wasm.interfaceStructs.get(iName)) {
          fatOpt = st;
        }
      }
      if (fatOpt == null) {
        return value;
      }
      let eqVt = new ValTypeEqRef() as ValType;
      let isNull = this.b.emit(IrOp.ref_is_null, new ValTypeI32(), value, -1);
      let extractB = this.b.newBlock();
      let merge = this.b.newBlock();
      let result = this.b.blockParam(merge, eqVt);
      let nullEq = this.b.emit(IrOp.ref_null, eqVt, -1, -1);
      this.b.brIf(isNull, merge, oneValue(nullEq),
          extractB, noValues());
      this.b.switchTo(extractB);
      let inst = this.fatPointerInstance(fatOpt, value);
      this.b.br(merge, oneValue(inst));
      this.b.switchTo(merge);
      return result;
    }
    return value;
  }

  /**
   * Whether a type test against `it` reads type info: some class can
   * answer it true (ReachabilityAnalysis's #markTypeTestPairs). When
   * none can, the test is the fat pointer test alone, and a value
   * that is not already an `it` answers false.
   */
  typeTestHasSlot(it: InterfaceType): boolean {
    let iKey = getInterfaceKey(it);
    return this.wasm.typeTestSlots.has(iKey) || this.wasm.typeTestChained.has(iKey);
  }

  /**
   * `value is it`, meaning the value's class implements `it`
   * (docs/design/interface-type-tests.md): true when the value is a
   * fat pointer of `it`, else when its class's type info holds a
   * vtable for `it`. A fixed sequence of loads and tests whatever the
   * number of implementers; #typeTestSlot does the lookup.
   */
  typeTestImplements(value: i32, it: InterfaceType): i32 {
    let i32vt = new ValTypeI32() as ValType;
    let merge = this.b.newBlock();
    let result = this.b.blockParam(merge, i32vt);
    let one = this.b.constI32(1, i32vt);
    let zero = this.b.constI32(0, i32vt);
    this.#typeTestFatPointer(value, it, merge, oneValue(one), false);
    if (this.wasm.typeTestChained.has(getInterfaceKey(it))) {
      this.#typeTestChain(value, it, (inst: i32, c: TypeTestCandidate): void => {
        this.b.br(merge, oneValue(one));
      });
      this.b.br(merge, oneValue(zero));
      this.b.switchTo(merge);
      return result;
    }
    let (slot, _) = this.#typeTestSlot(value, it, merge, oneValue(zero));
    if (slot < 0) {
      this.b.br(merge, oneValue(zero));
    } else {
      let isNull = this.b.emit(IrOp.ref_is_null, i32vt, slot, -1);
      let res = this.b.emit(IrOp.i32_eqz, i32vt, isNull, -1);
      this.b.br(merge, oneValue(res));
    }
    this.b.switchTo(merge);
    return result;
  }

  /**
   * `value as it` with the same meaning: the fat pointer of `it` for
   * the value, built around the instance with the class-interface
   * vtable its type info holds. Traps when the class does not
   * implement `it`. With `nullable`, a null value is null.
   */
  typeTestPack(value: i32, it: InterfaceType, nullable: boolean): i32 {
    let iKey = getInterfaceKey(it);
    let fatOpt = if (let (true, st) = this.wasm.interfaceStructs.get(iKey)) st else null;
    if (fatOpt == null) {
      this.fail('interface struct not found');
    }
    let fat = fatOpt;
    let fatVt = new ValTypeRef(fat) as ValType;
    let resultVt: ValType = if (nullable) new ValTypeRefNull(fat) else fatVt;
    let i32vt = new ValTypeI32() as ValType;
    let merge = this.b.newBlock();
    let result = this.b.blockParam(merge, resultVt);
    let vt = this.valueTypeOf(value);
    if (nullable && isRefValType(vt) && !(vt is ValTypeRef)) {
      let isNull = this.b.emit(IrOp.ref_is_null, i32vt, value, -1);
      let nullValue = this.b.emit(IrOp.ref_null, resultVt, -1, -1);
      let cont = this.b.newBlock();
      this.b.brIf(isNull, merge, oneValue(nullValue), cont, noValues());
      this.b.switchTo(cont);
    }
    let fatTested = this.#typeTestFatPointer(value, it, merge, noValues(), true);
    if (this.wasm.typeTestChained.has(iKey)) {
      let fatStruct = fat;
      let tested = this.#typeTestChain(value, it, (inst: i32, c: TypeTestCandidate): void => {
        let classVt = new ValTypeRef(c.structType) as ValType;
        let cast = this.b.emit(IrOp.ref_cast, classVt, inst, this.b.internType(classVt));
        let packed = this.b.emit(IrOp.iface_pack, new ValTypeRef(fatStruct) as ValType,
            cast, this.b.addRef(new IrRefGlobal(c.vtableGlobal)));
        this.b.br(merge, oneValue(packed));
      });
      // No candidate matched: the cast traps. With nothing to test at
      // all, the cast is statically impossible, and `merge` has no
      // predecessor for block cleanup to keep.
      this.b.unreachable();
      if (!fatTested && !tested) {
        this.b.switchTo(this.b.newBlock());
        return this.b.emit(IrOp.ref_null, resultVt, -1, -1);
      }
      this.b.switchTo(merge);
      return result;
    }
    let trapB = this.b.newBlock();
    let (slot, inst) = this.#typeTestSlot(value, it, trapB, noValues());
    if (slot < 0) {
      // No class the value can be implements `it`: the cast traps.
      this.b.unreachable();
      this.b.switchTo(trapB);
      this.b.unreachable();
    } else {
      let vstVt = this.valueTypeOf(slot);
      let vstNN: ValType = match (vstVt) {
        case ValTypeRefNull as rn: new ValTypeRef(rn.target)
        case _: vstVt
      };
      let vtable = this.b.emit(IrOp.ref_as_non_null, vstNN, slot, -1);
      let packed = this.b.emit(IrOp.struct_new, fatVt,
          this.b.pushArgList(growable<i32>([inst, vtable])),
          this.b.addRef(new IrRefType(fat)));
      this.b.br(merge, oneValue(packed));
      this.b.switchTo(trapB);
      this.b.unreachable();
    }
    this.b.switchTo(merge);
    return result;
  }

  /**
   * `typeTestPack` for a value stored at `want`, when `want` is an
   * interface fat pointer some test reads type info for: a narrowed
   * read, or a pattern binding, of a value that is not that fat
   * pointer. Returns -1 when `want` is not such a slot.
   */
  typeTestPackForSlot(value: i32, want: ValType): i32 {
    let stOpt = asWasmStruct(want);
    if (stOpt == null) {
      return -1;
    }
    let st = stOpt;
    // A value that is that fat pointer already (nullable, say) is the
    // caller's cast or re-assertion, not a pack.
    if (asWasmStruct(this.valueTypeOf(value)) === st) {
      return -1;
    }
    var key: InterfaceKey | null = null;
    for (let pair in this.wasm.interfaceStructs) {
      if (pair.value === st) {
        key = pair.key;
        break;
      }
    }
    if (key == null) {
      return -1;
    }
    for (let it in this.wasm.typeTestSlotInterfaces) {
      if (getInterfaceKey(it) == (key as InterfaceKey)) {
        return this.typeTestPack(value, it, want is ValTypeRefNull);
      }
    }
    if (let (true, it) = this.wasm.typeTestChained.get(key as InterfaceKey)) {
      return this.typeTestPack(value, it, want is ValTypeRefNull);
    }
    return -1;
  }

  /** Whether `st` is some interface's fat pointer struct. */
  #isInterfaceStruct(st: WasmStruct): boolean {
    for (let pair in this.wasm.interfaceStructs) {
      if (pair.value === st) {
        return true;
      }
    }
    return false;
  }

  /**
   * Branches to `target` when `value` is already a fat pointer of
   * `it` — with `args`, or with the value cast to the fat pointer when
   * `passCast` — and continues otherwise. Emits nothing for a value
   * whose static type cannot be one: a class instance, or a fat
   * pointer of another interface.
   */
  #typeTestFatPointer(value: i32, it: InterfaceType, target: i32,
      args: GrowableArray<i32>, passCast: boolean): boolean {
    let vt = this.valueTypeOf(value);
    if (!isRefValType(vt)) {
      return false;
    }
    let fatOpt = if (let (true, st) = this.wasm.interfaceStructs.get(getInterfaceKey(it))) st else null;
    if (fatOpt == null) {
      return false;
    }
    let fat = fatOpt;
    let st = asWasmStruct(vt);
    if (st != null && st !== fat &&
        (st.classType != null || this.#isInterfaceStruct(st))) {
      return false;
    }
    let fatVt = new ValTypeRef(fat) as ValType;
    let i32vt = new ValTypeI32() as ValType;
    let isFat = this.b.emit(IrOp.ref_test, i32vt, value, this.b.internType(fatVt));
    let cont = this.b.newBlock();
    if (passCast) {
      let yes = this.b.newBlock();
      this.b.brIf(isFat, yes, noValues(), cont, noValues());
      this.b.switchTo(yes);
      let cast = this.b.emit(IrOp.ref_cast, fatVt, value, this.b.internType(fatVt));
      this.b.br(target, oneValue(cast));
    } else {
      this.b.brIf(isFat, target, args, cont, noValues());
    }
    this.b.switchTo(cont);
    return true;
  }

  /**
   * The classes a chained test against `it` tries: the candidate
   * pairs of `it` (ReachabilityAnalysis's #markTypeTestPairs), less
   * the classes a class-typed operand cannot be. Each comes with the
   * pair vtable an `as` packs with.
   */
  #typeTestCandidates(value: i32, it: InterfaceType): GrowableArray<TypeTestCandidate> {
    let wasm = this.wasm;
    let iKey = getInterfaceKey(it);
    var bound: WasmStruct | null = null;
    let st = asWasmStruct(this.valueTypeOf(value));
    if (st != null && st.classType != null) {
      bound = st;
    }
    let candidates = new Array<TypeTestCandidate>();
    for (let cPair in wasm.typeTestClasses) {
      let key = getClassInterfaceKey(cPair.key, iKey);
      if (!wasm.typeTestPairs.has(key)) {
        continue;
      }
      let info = wasm.classInfos[cPair.key];
      if (bound != null) {
        var s: WasmStruct | null = info.structType;
        var below = false;
        while (s != null) {
          if (s === bound) {
            below = true;
            break;
          }
          s = s.superStruct;
        }
        if (!below) {
          continue;
        }
      }
      let g = wasm.getClassInterfaceVTable(key);
      if (g == null) {
        this.fail(`interface vtable global not found: ${cPair.key as String} as ${iKey as String}`);
      }
      candidates.push(new TypeTestCandidate(info.structType, g));
    }
    return candidates;
  }

  /**
   * A chain of class tests for `it` over `value`: `onHit` emits the
   * branch out for a candidate the instance passed, in a block where
   * `inst` is the instance; execution falls through when none passed.
   * Each test is a `ref.test` against a final struct, an inline
   * compare. An operand that can hold a fat pointer of another
   * interface is unwrapped through `FatPtrBase` after the chain
   * misses, and the chain runs again on the instance inside; the
   * miss path pays that open-type test, hits never do. Returns
   * whether any test was emitted.
   */
  #typeTestChain(value: i32, it: InterfaceType,
      onHit: (inst: i32, c: TypeTestCandidate) => void): boolean {
    let candidates = this.#typeTestCandidates(value, it);
    let i32vt = new ValTypeI32() as ValType;
    let vt = this.valueTypeOf(value);
    if (!isRefValType(vt)) {
      return false;
    }
    let st = asWasmStruct(vt);
    var inst = value;
    var tested = false;
    if (st != null && this.#isInterfaceStruct(st)) {
      if (candidates.length == 0) {
        return false;
      }
      if (vt is ValTypeRefNull) {
        let isNull = this.b.emit(IrOp.ref_is_null, i32vt, value, -1);
        let cont = this.b.newBlock();
        let miss = this.b.newBlock();
        this.b.brIf(isNull, miss, noValues(), cont, noValues());
        this.b.switchTo(cont);
        inst = this.fatPointerInstance(st, value);
        this.#typeTestChainOver(inst, candidates, onHit);
        this.b.br(miss, noValues());
        this.b.switchTo(miss);
        return true;
      }
      inst = this.fatPointerInstance(st, value);
      this.#typeTestChainOver(inst, candidates, onHit);
      return true;
    }
    if (candidates.length > 0) {
      this.#typeTestChainOver(inst, candidates, onHit);
      tested = true;
    }
    let baseOpt = this.wasm.fatPointerBaseStruct;
    if (baseOpt != null && candidates.length > 0 &&
        !(st != null && st.classType != null)) {
      let base = baseOpt;
      let baseVt = new ValTypeRef(base) as ValType;
      let isFat = this.b.emit(IrOp.ref_test, i32vt, inst, this.b.internType(baseVt));
      let unwrap = this.b.newBlock();
      let miss = this.b.newBlock();
      this.b.brIf(isFat, unwrap, noValues(), miss, noValues());
      this.b.switchTo(unwrap);
      let fat = this.b.emit(IrOp.ref_cast, baseVt, inst, this.b.internType(baseVt));
      let inner = this.b.emit(IrOp.struct_get, new ValTypeAnyRef(), fat,
          this.b.addRef(new IrRefField(base, 'instance')));
      this.#typeTestChainOver(inner, candidates, onHit);
      this.b.br(miss, noValues());
      this.b.switchTo(miss);
      tested = true;
    }
    return tested;
  }

  #typeTestChainOver(inst: i32, candidates: GrowableArray<TypeTestCandidate>,
      onHit: (inst: i32, c: TypeTestCandidate) => void): void {
    let i32vt = new ValTypeI32() as ValType;
    for (let c in candidates) {
      let classVt = new ValTypeRef(c.structType) as ValType;
      let isClass = this.b.emit(IrOp.ref_test, i32vt, inst, this.b.internType(classVt));
      let hit = this.b.newBlock();
      let next = this.b.newBlock();
      this.b.brIf(isClass, hit, noValues(), next, noValues());
      this.b.switchTo(hit);
      onHit(inst, c);
      this.b.switchTo(next);
    }
  }

  /**
   * The `TypeInfo` slot for `it` of the class of `value` — a nullable
   * reference to the class-interface vtable, null when the class does
   * not implement `it` — and the instance the value holds. Branches
   * to `fail` with `failArgs` when the value has no type info: it is
   * null, not a class instance, or an instance of a class in no
   * candidate hierarchy. Returns a slot of -1, emitting nothing, when
   * the static type says there is no slot to read.
   *
   * A class-typed value reads its own `<vtable>`; an interface-typed
   * one is unwrapped through its fat pointer struct; any other value
   * is unwrapped through `FatPtrBase` when it is a fat pointer, then
   * cast to `Object`.
   */
  #typeTestSlot(value: i32, it: InterfaceType, fail: i32,
      failArgs: GrowableArray<i32>): (i32, i32) {
    let wasm = this.wasm;
    let typeInfoOpt = wasm.typeInfoStruct;
    let vtableBaseOpt = wasm.vtableBaseStruct;
    if (typeInfoOpt == null || vtableBaseOpt == null) {
      return (-1, value);
    }
    let typeInfo = typeInfoOpt;
    let vtableBase = vtableBaseOpt;
    let iKey = getInterfaceKey(it);
    if (!wasm.typeTestSlots.has(iKey)) {
      return (-1, value);
    }
    let slotName = typeTestSlotName(wasm.typeTestSlots[iKey]);
    let vt = this.valueTypeOf(value);
    if (!isRefValType(vt)) {
      return (-1, value);
    }
    let i32vt = new ValTypeI32() as ValType;
    let st = asWasmStruct(vt);
    var ti = -1;
    var inst = value;
    if (st != null && st.classType != null) {
      let infoOpt = if (let (true, i) = wasm.classInfos.get(getClassKey(st.classType as ClassType))) i else null;
      if (infoOpt == null || infoOpt.vtableStructType == null) {
        return (-1, value);
      }
      let vstRoot = rootStruct(infoOpt.vtableStructType as WasmStruct);
      if (vstRoot.fieldIndexByName('<typeinfo>') < 0) {
        return (-1, value);
      }
      if (vt is ValTypeRefNull) {
        let isNull = this.b.emit(IrOp.ref_is_null, i32vt, value, -1);
        let cont = this.b.newBlock();
        this.b.brIf(isNull, fail, failArgs, cont, noValues());
        this.b.switchTo(cont);
        inst = this.reassertNonNull(value, new ValTypeRef(st));
      }
      let vtRaw = this.b.emit(IrOp.struct_get, this.fieldValType(st, '<vtable>'),
          inst, this.b.addRef(new IrRefField(st, '<vtable>')));
      ti = this.#typeInfoOfVTable(vtRaw, vstRoot, typeInfo, fail, failArgs);
    } else {
      let objOpt = wasm.objectStruct;
      if (objOpt == null) {
        return (-1, value);
      }
      let obj = objOpt;
      if (st != null && this.#isInterfaceStruct(st)) {
        if (vt is ValTypeRefNull) {
          let isNull = this.b.emit(IrOp.ref_is_null, i32vt, value, -1);
          let cont = this.b.newBlock();
          this.b.brIf(isNull, fail, failArgs, cont, noValues());
          this.b.switchTo(cont);
        }
        inst = this.fatPointerInstance(st, value);
      }
      // `Object` and `FatPtrBase` are open types, so wasmtime answers
      // a test against either with the `is_subtype` libcall whenever
      // the exact-type compare fails, which it always does here
      // (docs/design/struct-finality.md). Test `Object` first: a raw
      // instance, the common case behind an `anyref`, then pays one
      // libcall; a fat pointer of another interface pays the
      // `FatPtrBase` test and a second `Object` cast after unwrapping.
      // `ok` takes the instance as an `Object`, which is also the
      // instance a pack stores.
      let objVt = new ValTypeRef(obj) as ValType;
      let ok = this.b.newBlock();
      let okValue = this.b.blockParam(ok, objVt);
      let isObj = this.b.emit(IrOp.ref_test, i32vt, inst, this.b.internType(objVt));
      let direct = this.b.newBlock();
      let notObj = this.b.newBlock();
      this.b.brIf(isObj, direct, noValues(), notObj, noValues());
      this.b.switchTo(direct);
      this.b.br(ok, oneValue(this.b.emit(IrOp.ref_cast, objVt, inst,
          this.b.internType(objVt))));
      this.b.switchTo(notObj);
      let baseOpt = wasm.fatPointerBaseStruct;
      if (baseOpt == null || (st != null && this.#isInterfaceStruct(st))) {
        // Nothing else the value could be holds an instance.
        this.b.br(fail, failArgs);
      } else {
        let base = baseOpt;
        let baseVt = new ValTypeRef(base) as ValType;
        let isFat = this.b.emit(IrOp.ref_test, i32vt, inst, this.b.internType(baseVt));
        let unwrap = this.b.newBlock();
        this.b.brIf(isFat, unwrap, noValues(), fail, failArgs);
        this.b.switchTo(unwrap);
        let fat = this.b.emit(IrOp.ref_cast, baseVt, inst, this.b.internType(baseVt));
        let inner = this.b.emit(IrOp.struct_get, new ValTypeAnyRef(), fat,
            this.b.addRef(new IrRefField(base, 'instance')));
        let innerIsObj = this.b.emit(IrOp.ref_test, i32vt, inner, this.b.internType(objVt));
        let innerOk = this.b.newBlock();
        this.b.brIf(innerIsObj, innerOk, noValues(), fail, failArgs);
        this.b.switchTo(innerOk);
        this.b.br(ok, oneValue(this.b.emit(IrOp.ref_cast, objVt, inner,
            this.b.internType(objVt))));
      }
      this.b.switchTo(ok);
      inst = okValue;
      let vtRaw = this.b.emit(IrOp.struct_get, new ValTypeRefNull(vtableBase),
          okValue, this.b.addRef(new IrRefField(obj, '<vtable>')));
      ti = this.#typeInfoOfVTable(vtRaw, vtableBase, typeInfo, fail, failArgs);
    }
    let tiNull = this.b.emit(IrOp.ref_is_null, i32vt, ti, -1);
    let slotB = this.b.newBlock();
    this.b.brIf(tiNull, fail, failArgs, slotB, noValues());
    this.b.switchTo(slotB);
    let tiNN = this.reassertNonNull(ti, new ValTypeRef(typeInfo));
    let slot = this.b.emit(IrOp.struct_get, this.fieldValType(typeInfo, slotName),
        tiNN, this.b.addRef(new IrRefField(typeInfo, slotName)));
    return (slot, inst);
  }

  /**
   * The `<typeinfo>` of a nullable vtable reference, read through
   * `owner` (the struct that declares the field for the reference's
   * type); branches to `fail` for a null vtable.
   */
  #typeInfoOfVTable(vtRaw: i32, owner: WasmStruct, typeInfo: WasmStruct,
      fail: i32, failArgs: GrowableArray<i32>): i32 {
    let i32vt = new ValTypeI32() as ValType;
    let vtNull = this.b.emit(IrOp.ref_is_null, i32vt, vtRaw, -1);
    let cont = this.b.newBlock();
    this.b.brIf(vtNull, fail, failArgs, cont, noValues());
    this.b.switchTo(cont);
    let vtVt = this.valueTypeOf(vtRaw);
    let vtNN = match (vtVt) {
      case ValTypeRefNull as rn: this.reassertNonNull(vtRaw, new ValTypeRef(rn.target))
      case _: vtRaw
    };
    return this.b.emit(IrOp.struct_get, new ValTypeRefNull(typeInfo), vtNN,
        this.b.addRef(new IrRefField(owner, '<typeinfo>')));
  }

  fatPointerInstance(fatPtr: WasmStruct, value: i32): i32 {
    let fatVt = new ValTypeRef(fatPtr) as ValType;
    var v = value;
    if (!isValSubtype(this.valueTypeOf(v), fatVt)) {
      v = this.b.emit(IrOp.ref_cast, fatVt, v, this.b.internType(fatVt));
    }
    let inst = this.b.emit(IrOp.iface_instance,
        fatPtr.fields[0].type, v, -1);
    let eqVt = new ValTypeEqRef() as ValType;
    if (this.valueTypeOf(inst) is ValTypeAnyRef) {
      return this.b.emit(IrOp.ref_cast, eqVt, inst, this.b.internType(eqVt));
    }
    return inst;
  }

  /**
   * The record dispatch registered for a record type's (sorted) field
   * shape. Discovery registers every checked record shape, so a miss
   * means the type never reached discovery — bail.
   */
  recordDispatchOf(rtIn: RecordType): RecordDispatchInfo {
    var rt = rtIn;
    if (rtIn.row != null && this.func != null) {
      let whole = substituteTypeParamsInFunctionContext(this.wasm, this.func, rtIn);
      if (whole is RecordType) {
        rt = whole;
      }
    }
    let fields = recordWasmFields(this.wasm, rt, this.func);
    let infoOpt = if (rt.isExistential)
        this.wasm.findExistentialDispatch(fields, sortedOptionalNames(rt))
        else this.wasm.findRecordDispatch(fields, sortedOptionalNames(rt));
    if (infoOpt == null) {
      this.fail('record shape not discovered');
    }
    return infoOpt;
  }

  /**
   * Direct call to a class operator member: a (+) b as a.+(b).
   * Resolves against the left VALUE's class when known (mirrors
   * method calls); the given checked class is the fallback.
   */
  operatorMemberOn(opMember: String, left: i32, right: i32,
      leftCt: ClassType, chosenFt: FunctionType | null = null): i32 {
    let slotName = if (chosenFt != null) opMember + getSignatureKey(chosenFt) else opMember;
    let fromValue = if (leftCt.isExtension) null else this.classTypeOfValue(left);
    let recvCt = fromValue ?? leftCt;
    let method = this.resolveDevirtualizedMethod(recvCt, slotName);
    if (method != null) {
      let sig = method.signature;
      if (sig.params.length != 2 || sig.returns.length != 1) {
        this.fail('operator method shape');
      }
      let recv = this.coerceTo(left, sig.params[0]);
      let arg = this.coerceTo(right, sig.params[1]);
      let funcRef = this.b.addRef(new IrRefFunc(method));
      let args = growable<i32>([recv, arg]);
      return this.b.callFunc(funcRef, args, sig.returns[0]);
    }
    // Overridden operators dispatch through the class vtable like any
    // other overridden method (member-lookup.md §5.5 — operators fold
    // into method resolution). The slot signature is the statically
    // resolved member's.
    var resolvedOpt: WasmFunction | null = null;
    var currClass: ClassType | null = recvCt;
    while (currClass != null && resolvedOpt == null) {
      var g: ClassType | null = currClass;
      while (g != null && resolvedOpt == null) {
        let key = getClassMethodKey(getClassKey(g), slotName);
        if (let (true, m) = this.wasm.classMethodMap.get(key)) {
          resolvedOpt = m;
        }
        g = g.genericSource;
      }
      currClass = currClass.superType;
    }
    if (resolvedOpt == null) {
      this.fail('operator dispatch');
    }
    let resolvedM = resolvedOpt;
    let vsig = resolvedM.signature;
    if (vsig.params.length != 2 || vsig.returns.length != 1) {
      this.fail('operator method shape');
    }
    let infoOpt = if (let (true, info) = this.wasm.classInfos.get(getClassKey(recvCt))) info else null;
    if (infoOpt == null) {
      this.fail('operator dispatch');
    }
    let classInfo = infoOpt;
    if (this.vtableSlotIndex(classInfo, slotName) < 0) {
      this.fail('operator dispatch');
    }
    let vrecv = this.coerceTo(left, vsig.params[0]);
    let varg = this.coerceTo(right, vsig.params[1]);
    let vargs = growable<i32>([vrecv, varg]);
    return this.lowerVtableCall(vrecv, classInfo, slotName, vsig,
        vargs, vsig.returns[0]);
  }

  /**
   * Direct or virtual call to a unary class operator member (`-a` as
   * `a.-()`). Mirrors `operatorMemberOn` with a receiver-only signature.
   */
  unaryOperatorMemberOn(opMember: String, operand: i32,
      operandCt: ClassType, chosenFt: FunctionType | null = null): i32 {
    let slotName = if (chosenFt != null) opMember + getSignatureKey(chosenFt) else opMember;
    let fromValue = if (operandCt.isExtension) null else this.classTypeOfValue(operand);
    let recvCt = fromValue ?? operandCt;
    let method = this.resolveDevirtualizedMethod(recvCt, slotName);
    if (method != null) {
      let sig = method.signature;
      if (sig.params.length != 1 || sig.returns.length != 1) {
        this.fail('unary operator method shape');
      }
      let recv = this.coerceTo(operand, sig.params[0]);
      let funcRef = this.b.addRef(new IrRefFunc(method));
      return this.b.callFunc(funcRef, oneValue(recv), sig.returns[0]);
    }
    var resolvedOpt: WasmFunction | null = null;
    var currClass: ClassType | null = recvCt;
    while (currClass != null && resolvedOpt == null) {
      var g: ClassType | null = currClass;
      while (g != null && resolvedOpt == null) {
        let key = getClassMethodKey(getClassKey(g), slotName);
        if (let (true, m) = this.wasm.classMethodMap.get(key)) {
          resolvedOpt = m;
        }
        g = g.genericSource;
      }
      currClass = currClass.superType;
    }
    if (resolvedOpt == null) {
      this.fail('unary operator dispatch');
    }
    let resolvedM = resolvedOpt;
    let vsig = resolvedM.signature;
    if (vsig.params.length != 1 || vsig.returns.length != 1) {
      this.fail('unary operator method shape');
    }
    let infoOpt = if (let (true, info) = this.wasm.classInfos.get(getClassKey(recvCt))) info else null;
    if (infoOpt == null) {
      this.fail('unary operator dispatch');
    }
    let classInfo = infoOpt;
    if (this.vtableSlotIndex(classInfo, slotName) < 0) {
      this.fail('unary operator dispatch');
    }
    let vrecv = this.coerceTo(operand, vsig.params[0]);
    return this.lowerVtableCall(vrecv, classInfo, slotName, vsig,
        oneValue(vrecv), vsig.returns[0]);
  }

  /** Symbols assigned anywhere inside `node` that are locals in scope. */
  assignedEnvSyms(node: Node): GrowableArray<SymbolId> {
    let result = new Array<SymbolId>();
    this.appendAssignedEnvSyms(node, result);
    return result;
  }

  appendAssignedEnvSyms(node: Node, out: GrowableArray<SymbolId>): void {
    let seen = new Set<SymbolId>();
    for (let existing in out) {
      seen.add(existing);
    }
    walkEnter(node, (n) => {
      if (n is AssignmentExpression) {
        if (n.left is Identifier) {
          let sym = this.func.model.resolve(n.left);
          if (sym != null) {
            let resolved = sym.resolveTarget();
            // Celled bindings mutate their heap cell, not the env
            // entry, so they never need merge parameters.
            if (this.env.has(resolved.id) && !seen.has(resolved.id) &&
                !this.isCelled(resolved.id)) {
              seen.add(resolved.id);
              out.push(resolved.id);
              this.symbols[resolved.id] = resolved;
            }
          }
        }
      }
    });
  }

  coerceTo(value: i32, target: ValType): i32 {
    let vt = this.valueTypeOf(value);
    if (this.refConforms(vt, target)) {
      return value;
    }
    let nonNull = this.b.emit(IrOp.ref_as_non_null, this.nonNullOf(vt), value, -1);
    if (!isValSubtype(this.valueTypeOf(nonNull), target)) {
      this.failConformance(nonNull, target, 'intrinsic operand type');
    }
    return nonNull;
  }

  nonNullOf(vt: ValType): ValType {
    return match (vt) {
      case ValTypeRefNull as rn: new ValTypeRef(rn.target) as ValType
      case ValTypeExternRef: new ValTypeRefExtern() as ValType
      case _: vt
    };
  }

  /**
   * Call-boundary conformance: argument and constructor-field slots
   * accept a strictly-wider ref value via a downcast, exactly like
   * stores into bindings (the parameter IS the callee's binding);
   * anything else stays a loud bail.
   */
  conformToSlot(value: i32, want: ValType, reason: String): i32 {
    let have = this.valueTypeOf(value);
    if (this.refConforms(have, want)) {
      return value;
    }
    // A nullable value whose non-null form already conforms: the
    // checker proved this use non-null; re-assert (a null here traps,
    // which is the re-assert contract everywhere else too).
    if (have is ValTypeRefNull && want is ValTypeRef) {
      let nn = new ValTypeRef(have.target) as ValType;
      if (isValSubtype(nn, want)) {
        return this.b.emit(IrOp.ref_as_non_null, nn, value, -1);
      }
    }
    if (have is ValTypeExternRef && want is ValTypeRefExtern) {
      let nn = new ValTypeRefExtern() as ValType;
      return this.b.emit(IrOp.ref_as_non_null, nn, value, -1);
    }
    let copied = this.copyTuple(value, have, want, reason);
    if (copied >= 0) {
      return copied;
    }
    if (!isRefValType(have) || !isValSubtype(want, have)) {
      this.failConformance(value, want, reason);
    }
    return this.b.emit(IrOp.ref_cast, want, value, this.b.internType(want));
  }

  /**
   * `value`, a tuple of struct `have`'s, as a tuple of `want`'s: a new
   * tuple built from its elements, each conformed to `want`'s element
   * type. The checker lets a tuple stand for a tuple of supertypes
   * element by element, but a wasm struct declares one supertype, so
   * `(Bird, i32)` and `(Animal, i32)` are unrelated structs (#483).
   * Tuples have no identity, so the copy cannot be observed. A null
   * passes through when `want` takes one. -1 when either side is not a
   * tuple, or the two have different elements.
   */
  copyTuple(value: i32, have: ValType, want: ValType, reason: String): i32 {
    let from = refTargetOf(have);
    let to = refTargetOf(want);
    if (!(from is WasmStruct) || !(to is WasmStruct) || !from.isTuple ||
        !to.isTuple || from.fields.length != to.fields.length) {
      return -1;
    }
    for (var i = 0; i < from.fields.length; i += 1) {
      if (from.fields[i].name != to.fields[i].name) {
        return -1;
      }
    }
    let toVt = new ValTypeRef(to) as ValType;
    if (have is ValTypeRefNull && want is ValTypeRefNull) {
      let isNull = this.b.emit(IrOp.ref_is_null, new ValTypeI32() as ValType,
          value, -1);
      let nullB = this.b.newBlock();
      let copyB = this.b.newBlock();
      let mergeB = this.b.newBlock();
      this.b.brIf(isNull, nullB, new Array<i32>(), copyB, new Array<i32>());
      this.b.switchTo(copyB);
      let copy = this.copyTupleElements(this.stripNonNull(value), from, to, reason);
      let result = this.b.blockParam(mergeB, want);
      this.b.br(mergeB, oneValue(copy));
      this.b.switchTo(nullB);
      this.b.br(mergeB, oneValue(this.b.emit(IrOp.ref_null, want, -1, -1)));
      this.b.switchTo(mergeB);
      this.reachable = true;
      return result;
    }
    // A nullable source into a non-null slot: the checker proved it
    // non-null, as conformToSlot's re-assert assumes.
    let source = if (have is ValTypeRefNull) this.stripNonNull(value) else value;
    let copy = this.copyTupleElements(source, from, to, reason);
    return if (want is ValTypeRefNull) copy else this.conformToSlot(copy, toVt, reason);
  }

  /**
   * The elements of `value`, a non-null tuple of struct `st`, that a
   * tuple of type `target` narrows: each class-typed element whose type is
   * narrower than the field holding it, which a struct shared by tuples
   * that meet widens to hold them all (#1137), and the same inside a
   * nested tuple. With `cast`, each is cast to the target's element type,
   * trapping when it is not one, and the result is -1. Otherwise the
   * result is the i32 test of all of them, or -1 when none is narrower.
   */
  tupleElementChecks(value: i32, st: WasmStruct, target: TupleType, cast: boolean): i32 {
    let i32Vt = new ValTypeI32() as ValType;
    var all = -1;
    for (var i = 0; i < target.elementTypes.length; i += 1) {
      let name = i32ToString(i);
      let index = st.fieldIndexByName(name);
      if (index < 0) {
        continue;
      }
      let fieldVt = st.fields[index].type;
      let elementType = baseType(target.elementTypes[i]);
      let wantVt = typeToValTypeWithSub(this.wasm, target.elementTypes[i], this.func);
      if (this.refConforms(fieldVt, wantVt) || !isRefValType(wantVt)) {
        continue;
      }
      let element = this.b.emit(IrOp.struct_get, fieldVt, value,
          this.b.addRef(new IrRefField(st, name)));
      var test = -1;
      let nested = refTargetOf(fieldVt);
      if (elementType is TupleType && nested is WasmStruct && fieldVt is ValTypeRef) {
        test = this.tupleElementChecks(element, nested, elementType, cast);
      } else if (cast) {
        this.b.emit(IrOp.ref_cast, wantVt, element, this.b.internType(wantVt));
      } else {
        test = this.b.emit(IrOp.ref_test, i32Vt, element, this.b.internType(wantVt));
      }
      if (test >= 0) {
        all = if (all < 0) test else this.b.binary(IrOp.i32_and, i32Vt, all, test);
      }
    }
    return all;
  }

  /** Whether a tuple of type `target` narrows some element of struct `st` (`tupleElementChecks`). */
  tupleNarrows(st: WasmStruct, target: TupleType): boolean {
    for (var i = 0; i < target.elementTypes.length; i += 1) {
      let index = st.fieldIndexByName(i32ToString(i));
      if (index < 0) {
        continue;
      }
      let fieldVt = st.fields[index].type;
      let wantVt = typeToValTypeWithSub(this.wasm, target.elementTypes[i], this.func);
      if (isRefValType(wantVt) && !this.refConforms(fieldVt, wantVt)) {
        return true;
      }
    }
    return false;
  }

  /** A tuple of struct `to` built from the elements of `value`, of `from`. */
  copyTupleElements(value: i32, from: WasmStruct, to: WasmStruct,
      reason: String): i32 {
    let elements = new Array<i32>();
    for (var i = 0; i < from.fields.length; i += 1) {
      let name = from.fields[i].name as String;
      let element = this.b.emit(IrOp.struct_get, from.fields[i].type, value,
          this.b.addRef(new IrRefField(from, name)));
      elements.push(this.conformToSlot(element, to.fields[i].type, reason));
    }
    return this.b.emit(IrOp.struct_new, new ValTypeRef(to) as ValType,
        this.b.pushArgList(elements), this.b.addRef(new IrRefType(to)));
  }

  /**
   * A call's receiver, conformed to the method's receiver slot. The
   * slot is non-null, and most receivers already are: identifier and
   * member reads re-assert to the checker's narrowed type. A nullable
   * value whose non-null form fits the slot is re-asserted here, which
   * traps on null like every other re-assert. Anything else bails: a
   * receiver that needs a downcast is a lowering bug, and the one
   * legitimate downcast (a `this`-returning call narrowed to the
   * subclass) goes through conformToSlot by name.
   */
  conformReceiver(value: i32, want: ValType, reason: String): i32 {
    let have = this.valueTypeOf(value);
    if (this.refConforms(have, want)) {
      return value;
    }
    if (have is ValTypeRefNull && want is ValTypeRef) {
      let nn = new ValTypeRef(have.target) as ValType;
      if (isValSubtype(nn, want)) {
        return this.b.emit(IrOp.ref_as_non_null, nn, value, -1);
      }
    }
    this.failConformance(value, want, reason);
    return value;
  }

  conformToBinding(value: i32, bindingVt: ValType): i32 {
    let have = this.valueTypeOf(value);
    if (this.refConforms(have, bindingVt)) {
      return value;
    }
    if (have is ValTypeRefNull && bindingVt is ValTypeRef) {
      // Nullable value into a non-null binding: the checker proved
      // this init non-null; re-assert (same-target) or cast down.
      let nn = new ValTypeRef(have.target) as ValType;
      if (isValSubtype(nn, bindingVt)) {
        return this.reassertNonNull(value, nn);
      }
    }
    if (have is ValTypeExternRef && bindingVt is ValTypeRefExtern) {
      let nn = new ValTypeRefExtern() as ValType;
      return this.reassertNonNull(value, nn);
    }
    if (isRefValType(have)) {
      // A binding declared at an interface some test reads type info
      // for, initialized from a value the checker narrowed to it: pack
      // through the class's type info.
      let packed = this.typeTestPackForSlot(value, bindingVt);
      if (packed >= 0) {
        return packed;
      }
    }
    let copied = this.copyTuple(value, have, bindingVt, 'binding value type');
    if (copied >= 0) {
      return copied;
    }
    if (isRefValType(have) && isValSubtype(bindingVt, have)) {
      return this.b.emit(IrOp.ref_cast, bindingVt, value,
          this.b.internType(bindingVt));
    }
    this.fail('binding value type');
  }

  bindPatternSym(sym: Symbol, value: i32): void {
    let bindingType = this.func.model.getBindingType(sym);
    if (bindingType == null) {
      this.fail('untyped match binding');
    }
    let bindingVt = typeToValTypeWithSub(this.wasm, bindingType, this.func);
    if (bindingVt is ValTypeVoid) {
      // A zero-width binding (a void lane's) holds nothing; a celled
      // one stays a loud miss, like every celled zero-width binding.
      if (this.isCelled(sym.id)) {
        this.fail('celled zero-width binding');
      }
      // -1 is lowering.zena's NO_VALUE; the value cannot cross this
      // module cycle's back edge (module-level bindings may not).
      this.env[sym.id] = -1;
      this.symbols[sym.id] = sym;
      return;
    }
    this.requireSupported(bindingVt, 'match binding type');
    var bound = value;
    let have = this.valueTypeOf(value);
    if (!valTypeIdentical(have, bindingVt) && !this.refConforms(have, bindingVt)) {
      let wantRef = bindingVt is ValTypeRef || bindingVt is ValTypeRefNull;
      if (!isRefValType(have) || !wantRef) {
        this.fail('match binding coercion');
      }
      // `case I as x` on a value that is not an `I` fat pointer: the
      // test that got here read the class's type info, and the binding
      // packs the same way.
      let packed = this.typeTestPackForSlot(value, bindingVt);
      bound = if (packed >= 0) packed else this.b.emit(IrOp.ref_cast,
          bindingVt, value, this.b.internType(bindingVt));
    }
    if (this.isCelled(sym.id)) {
      this.env[sym.id] = this.cellAlloc(bindingVt, bound);
    } else {
      this.env[sym.id] = bound;
    }
    this.symbols[sym.id] = sym;
  }

  /**
   * Celled = captured by a closure and assigned after some closure
   * captured it, on either side of the boundary (capturedInCell). The
   * variable lives in a heap cell shared through closure contexts; the
   * environment maps the symbol to the cell REFERENCE, so reads and
   * writes go through the cell's `value` field. The reference is an
   * invariant SSA value, so a celled binding is no merge parameter,
   * with one exception: a `for` header's variable gets a fresh cell
   * each iteration, and the loop carries it (lowerFor).
   */
  isCelled(symId: SymbolId): boolean {
    return this.wasm.mutableCapturedSymbols.has(symId);
  }

  /**
   * Cells pre-allocated (empty) by precellBindings, awaiting their
   * declaration's write-through. Consumed there, so a re-lowered
   * declaration (none today) or later shadowing allocates fresh.
   */
  precelledBindings = new Set<SymbolId>();

  /**
   * Enclosing locals assigned inside an ACTIVE `try` body, mapped to
   * the mutable variable mirroring them (ir.md §5.1).
   *
   * The binding stays an ordinary SSA variable everywhere — reads,
   * merges and loop carries are untouched, so there is no cost to
   * reading one. The mirror exists for the handler alone, which no SSA
   * edge can reach carrying the body's assignments: the protected edge
   * leaves from anywhere in the region and can only carry values live
   * at its entry. So every assignment ALSO writes the variable, and
   * the handler seeds its environment by reading it back.
   *
   * Nested tries share one variable per symbol: the innermost handler
   * wants the same "last value written" the outer one does.
   */
  tryVars = new Map<SymbolId, i32>();

  /**
   * The `finally` regions enclosing the statement being lowered,
   * innermost last. Non-empty means an exit out of one of them —
   * `return` always, `break`/`continue` when their loop was opened
   * outside — must run finalizers instead of branching to its target,
   * which `returnThroughFinally`/`breakThroughFinally`/
   * `continueThroughFinally` (control-flow.zena) arrange.
   */
  finallyScopes = new Array<FinallyScope>();

  /**
   * `var` owner bindings whose release region is open around the
   * statements being lowered, so a nested statement list — a `using`
   * region's rest, a value block — opens no second region for one and
   * releases its value twice on unwind (control-flow.zena
   * `lowerStatementRange`).
   */
  openVarDrops = new Set<i32>();

  /**
   * Mirrors a newly stored value into the symbol's try variable, when
   * it has one. Every site that stores an SSA value for a symbol into
   * `env` must call this — a missed one leaves the handler reading a
   * stale value.
   */
  noteVarWrite(symId: SymbolId, value: i32): void {
    if (let (true, varId) = this.tryVars.get(symId)) {
      this.b.varSet(varId,
          this.conformToSlot(value, this.b.body.varTypes[varId], 'try var type'));
    }
  }

  /**
   * Pre-allocates empty cells for celled `let f = (…) => …` bindings
   * in a statement list, BEFORE any statement lowers. Self- and
   * forward-referencing closures capture the binding before its
   * declaration executes; the cell is the identity they share, and
   * the declaration later writes the closure value through it. Only
   * nullable-ref cells can start empty; celled bindings of other
   * shapes keep the declaration-time allocation (and closures created
   * before it keep failing loudly, as before).
   */
  precellBindings(body: GrowableArray<Statement>): void {
    for (let stmt in body) {
      if (!(stmt is VariableDeclaration)) { continue; }
      var pat = stmt.pattern;
      if (pat is BindingPattern) {
        pat = pat.pattern;
      }
      if (!(pat is IdentifierPattern)) { continue; }
      if (!(stmt.init is FunctionExpression)) { continue; }
      let sym = this.func.model.resolveDeclaration(pat);
      if (sym == null) { continue; }
      if (!this.isCelled(sym.id) || this.env.has(sym.id)) { continue; }
      let bindingType = this.func.model.getBindingType(sym);
      if (bindingType == null) { continue; }
      let bindingVt = typeToValTypeWithSub(this.wasm, bindingType, this.func);
      // Same invariant as cellAlloc: post-layout, the cell shape must
      // already be interned by discovery or its casts emit heap type -1.
      if (this.wasm.isLayoutLocked &&
          !this.wasm.cellStructs.has(getCellKey(bindingVt))) {
        throw new Error('cell struct not laid out (discovery bug): ' +
            (this.func.name ?? '<unnamed>'));
      }
      let cellStruct = getCellStruct(this.wasm, bindingVt);
      let fieldVt = cellStruct.fields[0].type;
      if (!(fieldVt is ValTypeRefNull)) { continue; }
      let nullVal = this.b.emit(IrOp.ref_null, fieldVt, -1, -1);
      let typeRef = this.b.addRef(new IrRefType(cellStruct));
      this.env[sym.id] = this.b.emit(IrOp.struct_new,
          new ValTypeRef(cellStruct) as ValType,
          this.b.pushArgList(oneValue(nullVal)), typeRef);
      this.symbols[sym.id] = sym;
      this.precelledBindings.add(sym.id);
    }
  }

  /** Allocates a fresh cell holding `value` for a celled binding. */
  cellAlloc(bindingVt: ValType, value: i32): i32 {
    // ZIR synthesis runs after layout: a getCellStruct MISS here would
    // mint a Cell struct that can never receive a type index (its
    // casts emit heap type -1 — invalid wasm). A miss means discovery
    // failed to intern this cell shape pre-layout — an invariant
    // violation, not a coverage gap — so fail the compile loudly
    // rather than masking it behind a streaming fallback.
    if (this.wasm.isLayoutLocked &&
        !this.wasm.cellStructs.has(getCellKey(bindingVt))) {
      throw new Error('cell struct not laid out (discovery bug): ' +
          (this.func.name ?? '<unnamed>'));
    }
    if (!isValSubtype(this.valueTypeOf(value), bindingVt)) {
      this.failConformance(value, bindingVt, 'cell init type');
    }
    let cellStruct = getCellStruct(this.wasm, bindingVt);
    let typeRef = this.b.addRef(new IrRefType(cellStruct));
    return this.b.emit(IrOp.struct_new,
        new ValTypeRef(cellStruct) as ValType,
        this.b.pushArgList(oneValue(value)), typeRef);
  }

  /** The cell struct behind a celled environment entry. */
  cellStructOf(cell: i32): WasmStruct {
    let st = asWasmStruct(this.valueTypeOf(cell));
    if (st != null) {
      return st;
    }
    throw new ZirUnsupported('celled binding shape');
  }

  cellRead(cell: i32): i32 {
    let cs = this.cellStructOf(cell);
    let fieldRef = this.b.addRef(new IrRefField(cs, 'value'));
    return this.b.emit(IrOp.struct_get, cs.fields[0].type, cell, fieldRef);
  }

  cellWrite(cell: i32, value: i32): void {
    let cs = this.cellStructOf(cell);
    if (!isValSubtype(this.valueTypeOf(value), cs.fields[0].type)) {
      this.failConformance(value, cs.fields[0].type, 'cell write type');
    }
    let fieldRef = this.b.addRef(new IrRefField(cs, 'value'));
    let pairIdx = this.b.pushExtra(twoValues(cell, value));
    this.b.emitVoid(IrOp.struct_set, pairIdx, fieldRef);
  }

  /**
   * Conforms an arm's result and brs to the merge, materializing it on
   * first use. Callers guard on reachability; `value` is ignored for
   * void merges.
   */
  mergeArm(m: MergeState, value: i32, armKind: String = 'arm type'): void {
    var v = value;
    if (!m.isVoid) {
      v = this.conformToSlot(v, m.resultVt as ValType, armKind);
    }
    if (m.block < 0) {
      m.block = this.b.newBlock();
      m.params = this.addParams(m.block, m.syms);
      if (!m.isVoid) {
        m.resultParam = this.b.blockParam(m.block, m.resultVt as ValType);
      }
    }
    let args = this.envValues(m.syms);
    if (!m.isVoid) {
      args.push(v);
    }
    this.b.br(m.block, args);
  }

  /**
   * Like mergeArm, for a merge in fields mode (MergeState.fields): the
   * arm passes its record's fields, not the record.
   */
  mergeArmFields(m: MergeState, values: GrowableArray<i32>): void {
    let d = m.fields as RecordDispatchInfo;
    if (m.block < 0) {
      m.block = this.b.newBlock();
      m.params = this.addParams(m.block, m.syms);
      let fieldParams = new Array<i32>();
      for (let field in d.fields) {
        fieldParams.push(this.b.blockParam(m.block, field.type));
      }
      m.fieldParams = fieldParams;
    }
    let args = this.envValues(m.syms);
    for (var i = 0; i < values.length; i += 1) {
      args.push(this.conformToSlot(values[i], d.fields[i].type, 'record arm field type'));
    }
    this.b.br(m.block, args);
  }

  /**
   * Like mergeArm, for a merge in slots mode (MergeState.slots): the arm
   * passes its inline value's slots.
   */
  mergeArmSlots(m: MergeState, values: GrowableArray<i32>): void {
    let slots = m.slots as ResultSlots;
    if (m.block < 0) {
      m.block = this.b.newBlock();
      m.params = this.addParams(m.block, m.syms);
      let slotParams = new Array<i32>();
      for (let vt in slots.slotVts) {
        slotParams.push(this.b.blockParam(m.block, vt));
      }
      m.slotParams = slotParams;
    }
    let args = this.envValues(m.syms);
    for (var i = 0; i < values.length; i += 1) {
      args.push(this.conformToSlot(values[i], slots.slotVts[i], 'inline arm slot type'));
    }
    this.b.br(m.block, args);
  }

  /**
   * Set just before lowering an inline `if` or `match` into slots, which
   * takes it (takeResultSlots), merges its arms' slots, and leaves the
   * merged slots in `mergedSlots`.
   */
  var resultSlots: ResultSlots | null = null;
  var mergedSlots: GrowableArray<i32> | null = null;

  takeResultSlots(): ResultSlots | null {
    let slots = this.resultSlots;
    this.resultSlots = null;
    return slots;
  }

  /**
   * Set by a core that returns its record as its fields just before it
   * lowers the `if` or `match` whose value it returns, which takes it
   * (takeResultFields) and merges its arms' fields instead of their
   * records.
   */
  var resultFields: RecordDispatchInfo | null = null;

  takeResultFields(): RecordDispatchInfo | null {
    let d = this.resultFields;
    this.resultFields = null;
    return d;
  }

  /**
   * Set by a function returning an inline value just before it lowers
   * the `if` or `match` whose value it returns, which takes it
   * (takeReturnTail) and returns from each arm instead of merging the
   * arms' values (MergeState.returnTail).
   */
  var returnTail = false;

  takeReturnTail(): boolean {
    let t = this.returnTail;
    this.returnTail = false;
    return t;
  }

  /**
   * `record`'s fields through `d`: the values it is held as, or each
   * field read off it.
   */
  recordFieldsOf(d: RecordDispatchInfo, record: i32): GrowableArray<i32> {
    if (let (true, held) = this.explodedRecords.get(record)) {
      if (held.dispatch === d) {
        return held.values;
      }
    }
    let values = new Array<i32>();
    for (let field in d.fields) {
      values.push(this.recordDispatchRead(d, field.name as String, record));
    }
    return values;
  }

  /**
   * Lands at the merge: restores the saved env view, rebinds the
   * tracked symbols to the merge params, and resumes there. Returns
   * the result param, or -1 when no arm reached the merge (the
   * expression is unreachable past this point).
   */
  finishMerge(m: MergeState, saved: HashMap<SymbolId, i32>): i32 {
    if (m.block < 0) {
      this.reachable = false;
      return -1;
    }
    this.env = saved;
    this.b.switchTo(m.block);
    this.applyParams(m.syms, m.params as GrowableArray<i32>);
    this.reachable = true;
    return m.resultParam;
  }

  addParams(block: i32, syms: GrowableArray<SymbolId>): GrowableArray<i32> {
    let params = new Array<i32>();
    for (let symId in syms) {
      // An inline var crosses the join as one parameter per slot.
      if (let (true, iv) = this.inlineVars.get(symId)) {
        for (let vt in iv.slotTypes) {
          params.push(this.b.blockParam(block, vt));
        }
        continue;
      }
      // A var held as its fields (ir/explode.zena) crosses the join as
      // one parameter per field.
      if (let (true, d) = this.wasm.fieldHeldVars.get(symId)) {
        for (let field in d.fields) {
          params.push(this.b.blockParam(block, field.type));
        }
        continue;
      }
      // The binding's declared type is the stable merge type: incoming
      // values may be wasm subtypes (non-null refs, subclass structs,
      // typed nulls), which the verifier's subtype check admits.
      var vt = this.bindingValType(symId);
      if (this.isCelled(symId)) {
        // Only a `for` header's variable carries its cell (lowerFor).
        vt = new ValTypeRef(getCellStruct(this.wasm, vt));
      }
      params.push(this.b.blockParam(block, vt));
    }
    return params;
  }

  /**
   * A record value: the struct built from `values`, packed with its
   * table; a tuple's (`RecordDispatchInfo.isTuple`) is the struct.
   */
  packRecord(d: RecordDispatchInfo, values: GrowableArray<i32>): i32 {
    let instance = this.b.emit(IrOp.struct_new,
        new ValTypeRef(d.concreteType) as ValType,
        this.b.pushArgList(values),
        this.b.addRef(new IrRefType(d.concreteType)));
    if (d.isTuple) {
      return instance;
    }
    return this.b.emit(IrOp.iface_pack,
        new ValTypeRef(d.fatPtrType) as ValType, instance,
        this.b.addRef(new IrRefGlobal(d.vtableGlobal)));
  }

  /**
   * A record value built from field values in `d.fields` order, held
   * as those fields (`explodedRecords`): it dies unless some use needs
   * the record whole.
   */
  heldRecord(d: RecordDispatchInfo, values: GrowableArray<i32>): i32 {
    let record = this.packRecord(d, values);
    this.explodedRecords[record] = new ExplodedRecord(d, values);
    return record;
  }

  /**
   * `record`'s fields for `d`: the values it is held as, or, for a
   * record not held, each field read through its getter (after which it
   * is held, so the next request reads nothing).
   */
  heldFields(d: RecordDispatchInfo, record: i32): GrowableArray<i32> {
    if (let (true, held) = this.explodedRecords.get(record)) {
      if (held.dispatch === d) {
        return held.values;
      }
    }
    let values = new Array<i32>();
    for (let field in d.fields) {
      values.push(this.coerceTo(
          this.recordDispatchRead(d, field.name as String, record),
          field.type));
    }
    this.explodedRecords[record] = new ExplodedRecord(d, values);
    return values;
  }

  bindingValType(symId: SymbolId): ValType {
    if (!this.symbols.has(symId)) {
      this.fail('unknown merge symbol');
    }
    let t = this.func.model.getBindingType(this.symbols[symId]);
    if (t == null) {
      this.fail('untyped merge binding');
    }
    let vt = typeToValTypeWithSub(this.wasm, t, this.func);
    this.requireSupported(vt, 'merge binding type');
    return vt;
  }

  applyParams(syms: GrowableArray<SymbolId>, params: GrowableArray<i32>): void {
    // A held var's field parameters are rebuilt into a held record here,
    // so this runs once the join block is current.
    var p = 0;
    for (let symId in syms) {
      if (let (true, iv) = this.inlineVars.get(symId)) {
        let slots = new Array<i32>();
        for (var k = 0; k < iv.slotTypes.length; k += 1) {
          slots.push(params[p + k]);
        }
        p += iv.slotTypes.length;
        this.env[symId] = iv.bind(slots);
        continue;
      }
      if (let (true, d) = this.wasm.fieldHeldVars.get(symId)) {
        let values = new Array<i32>();
        for (var k = 0; k < d.fields.length; k += 1) {
          values.push(params[p + k]);
        }
        p += d.fields.length;
        this.env[symId] = this.heldRecord(d, values);
        continue;
      }
      this.env[symId] = params[p];
      p += 1;
    }
  }

  envValues(syms: GrowableArray<SymbolId>): GrowableArray<i32> {
    let values = new Array<i32>();
    for (let symId in syms) {
      if (this.isCelled(symId)) {
        values.push(this.env[symId]);
        continue;
      }
      // Branch arguments must conform to the params addParams typed
      // from the DECLARED binding: env narrowing (a nullable value
      // proven non-null and re-widened by a merge, or vice versa)
      // can leave the current value at a different nullability than
      // the binding. conformToBinding re-asserts or downcasts; exact
      // matches pass through untouched.
      if (let (true, iv) = this.inlineVars.get(symId)) {
        let slots = iv.slotsOf(this.env[symId]);
        for (var k = 0; k < slots.length; k += 1) {
          values.push(this.conformToSlot(slots[k], iv.slotTypes[k], 'inline var slot'));
        }
        continue;
      }
      if (let (true, d) = this.wasm.fieldHeldVars.get(symId)) {
        for (let v in this.heldFields(d, this.env[symId])) {
          values.push(v);
        }
        continue;
      }
      values.push(this.conformToBinding(this.env[symId],
          this.bindingValType(symId)));
    }
    return values;
  }

  copyEnv(): HashMap<SymbolId, i32> {
    return this.copyOf(this.env);
  }

  copyOf(source: HashMap<SymbolId, i32>): HashMap<SymbolId, i32> {
    let copy = new Map<SymbolId, i32>();
    for (let pair in source) {
      copy[pair.key] = pair.value;
    }
    return copy;
  }
}

/** An empty argument list (branch with no args, nullary call). */
export function noValues(): GrowableArray<i32> {
  return new Array<i32>();
}

/** A one-element argument list (single branch arg or call operand). */
export function oneValue(a: i32): GrowableArray<i32> {
  let list = growable<i32>([a]);
  return list;
}

/** A two-element argument list, in push order. */
export function twoValues(a: i32, b: i32): GrowableArray<i32> {
  let list = growable<i32>([a, b]);
  return list;
}

/**
 * Repacks a fat pointer of interface `srcName` into one of `tgtName`,
 * which it extends: the same instance, and a vtable of the target's
 * slots copied out of the source's by name. A free function so that a
 * synthesized body with only a builder (the function-adaptation
 * wrapper) can make the upcast; LoweringContext.repackInterface calls
 * it too.
 */
export function repackInterfaceValue(wasm: WasmModule, b: IrBuilder, value: i32,
    srcName: InterfaceKey, tgtName: InterfaceKey): i32 {
  if (srcName == tgtName) {
    return value;
  }
  let srcFatOpt = if (let (true, st) = wasm.interfaceStructs.get(srcName)) st else null;
  let srcVstOpt = if (let (true, st) = wasm.interfaceVTableStructs.get(srcName)) st else null;
  let tgtFatOpt = if (let (true, st) = wasm.interfaceStructs.get(tgtName)) st else null;
  let tgtVstOpt = if (let (true, st) = wasm.interfaceVTableStructs.get(tgtName)) st else null;
  if (srcFatOpt == null || srcVstOpt == null || tgtFatOpt == null || tgtVstOpt == null) {
    throw new ZirUnsupported('interface struct not found');
  }
  let srcFat = srcFatOpt;
  let srcVst = srcVstOpt;
  let tgtFat = tgtFatOpt;
  let tgtVst = tgtVstOpt;
  let srcFatVt = new ValTypeRef(srcFat) as ValType;
  var srcVal = value;
  if (!isValSubtype(b.body.resultType(srcVal) as ValType, srcFatVt)) {
    srcVal = b.emit(IrOp.ref_cast, srcFatVt, srcVal, b.internType(srcFatVt));
  }
  let inst = b.emit(IrOp.iface_instance, srcFat.fields[0].type, srcVal, -1);
  let srcVt = b.emit(IrOp.iface_vtable, srcFat.fields[1].type, srcVal, -1);
  let vtFields = new Array<i32>();
  for (let f in tgtVst.fields) {
    let fName = f.name as String;
    let idx = srcVst.fieldIndexByName(fName);
    if (idx < 0) {
      throw new ZirUnsupported('interface upcast slot missing: ' + fName);
    }
    let slotVal = b.emit(IrOp.struct_get, srcVst.fields[idx].type, srcVt,
        b.addRef(new IrRefField(srcVst, fName)));
    if (!isValSubtype(b.body.resultType(slotVal) as ValType, f.type)) {
      throw new ZirUnsupported('interface upcast slot signature mismatch: ' + fName);
    }
    vtFields.push(slotVal);
  }
  let tgtVt = b.emit(IrOp.struct_new,
      new ValTypeRef(tgtVst) as ValType,
      b.pushArgList(vtFields),
      b.addRef(new IrRefType(tgtVst)));
  return b.emit(IrOp.struct_new,
      new ValTypeRef(tgtFat) as ValType,
      b.pushArgList(twoValues(inst, tgtVt)),
      b.addRef(new IrRefType(tgtFat)));
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19