wit-parser 0.0.1-preview.1

A WIT (WebAssembly Interface Types) parser, resolver and component encoder

Readme Files Dependencies Versions

wit-parser#

A WebAssembly Interface Types (WIT) parser, semantic resolver, .wit.json serializer, and component type encoder for Zena.

Installation#

zena pkg add zena-lang:wit-parser

Example#

import { parse } from 'zena-lang:wit-parser';
import { AstItemTag } from 'zena-lang:wit-parser/parser';

let source = `
package example:greeter@1.0.0;

interface greet {
  record greeting { text: string, formal: bool }
  hello: func(name: string) -> greeting;
}

interface farewell {
  use greet.{greeting};
  goodbye: func(name: string) -> greeting;
}

world greeter {
  export greet;
  export farewell;
}
`;

// Parses syntax and resolves names and cross-interface `use` references.
// Throws `ParseError` or `ResolveError` if the document is invalid.
let doc = parse(source);

var interfaces = 0;
var worlds = 0;
for (let item in doc.items) {
  if (item.tag == AstItemTag.Interface) {
    interfaces += 1;
  } else if (item.tag == AstItemTag.World) {
    worlds += 1;
  }
}

Libraries#

zena-lang:wit-parser#

The primary entry point for parsing, resolving, and serializing WIT source text.

Function Description
parse(source) Parses and resolves source into a validated Ast. Throws ParseError or ResolveError.
parseSyntax(source) Parses source without resolving names, for single-file syntax tooling such as formatters.
resolve(ast) Resolves names and validates an Ast in place.
toJson(ast, packageOrder?) Serializes a resolved Ast to the .wit.json format emitted by wasm-tools component wit --json.

zena-lang:wit-parser also re-exports Ast, ParseError, and ResolveError. Both error types carry a Span with byte offsets into the source text.

zena-lang:wit-parser/parser#

The AST node declarations (Ast, AstItem, AstItemTag, InterfaceDef, WorldDef, TypeDef, Type, NamedFunc, ResourceFunc, Use, Include, Docs, Attribute, PackageName, NestedPackage, and related types) and Parser.

zena-lang:wit-parser/document#

Utilities for assembling multi-file WIT directories into a single source document while tracking file boundaries for error reporting:

  • WitFile(name, source) and joinWitDocument(files): concatenates .wit files in canonical name order and records where each file starts.
  • WitDocument.locate(offset): maps a byte offset back to a WitLocation (file, 1-based line, 1-based column).
  • witDiagnostic(doc, error): formats a LexError, ParseError, or ResolveError with its filename, line, column, source line, and caret underline.
  • findInterface(ast, namespace, interfacePath): looks up an interface (pkg/iface) in a parsed document.

zena-lang:wit-parser/component-encoder#

Encodes a resolved WIT world into WebAssembly Component Model binary type and import sections:

  • encodeTypesOnlyComponent(ast, worldName): encodes the named world as a standalone types-only component binary.
  • ComponentTypeEncoder: emits component type, alias, import, and export sections and canonical ABI metadata (WitFuncMeta, WitFlatMeta).
  • expandedWorldItems(ast, world) and worldNames(ast): expands world includes and transitive use dependencies.

zena-lang:wit-parser/lexer and zena-lang:wit-parser/token#

Low-level tokenization: Lexer, LexError, Token, TokenType, and Span.

zena-lang:wit-parser/resolver#

Semantic validation and name resolution: Resolver and ResolveError.

85.8 KiB Raw
/**
 * The WIT type encoder: a resolved document's world, as the type and
 * import sections of a component binary.
 *
 * This is the encoding half of what `wasm-tools component embed` does —
 * each imported interface becomes an instance type whose declarations
 * spell out its types and functions, and the component imports one
 * instance per interface. The compiler's component target consumes the
 * emitted pieces to head its own component; `encodeTypesOnlyComponent`
 * wraps the same pieces in a bare component so the encoding can be
 * verified on its own, by handing the bytes back to
 * `wasm-tools component wit`.
 *
 * The encoding rules that are easy to get wrong, verified against
 * `wasm-tools 1.252.0` byte for byte:
 *
 * - A type index in *value-type position* is a signed LEB128, because
 *   the primitive opcodes (`0x64`–`0x7f`) are its negative range. An
 *   index of 79 is two bytes. Indices in every other position (type
 *   bounds, `own`, export declarations) are unsigned.
 * - Every WIT-*named* type — record, variant, enum, flags, resource,
 *   `type` alias — must be **exported** from the instance type, and it
 *   is the *export* that creates the index everything else refers to.
 *   An instance type that keeps a record anonymous validates on its
 *   own and then fails at the import with "instance not valid to be
 *   used as import". Anonymous constructors (`list`, `tuple`,
 *   `option`, `result`, `own`, `borrow`) need no export.
 * - A `use`d type crosses instances in two hops: at component level an
 *   `alias export` pulls it out of the already-imported source
 *   instance, and inside the dependent instance type an `alias outer`
 *   (count 1: the enclosing component) brings it back in, where it is
 *   re-exported under its local name.
 * - A method's `self: borrow<R>` parameter is implicit in WIT and
 *   explicit in the binary; a constructor returns `own<R>` the same
 *   way. Resource function export names carry the `[constructor]r` /
 *   `[method]r.f` / `[static]r.f` prefixes.
 *
 * What this does not encode yet, each a loud `EncodeError` rather than
 * wrong bytes: `future`, `stream`, `map` and `error-context` (their
 * runtime is C6), fixed-length lists, world-level `use` and type
 * definitions, and `include`. A world's *exports* are skipped rather
 * than rejected — a types-only component has nothing to implement them
 * with, and the compiler's own export machinery is what lifts real
 * functions — and the skipped names are reported on the result so a
 * caller can say so.
 */

import { ByteBuffer } from 'zena:core';
import {
  Ast, AstItem, AstItemTag, InterfaceDef, WorldDef, InterfaceItem,
  InterfaceItemTag, TypeDef, TypeDefTag, Type, TypeTag, NamedFunc, Func,
  ResourceFunc, ResourceFuncTag, Use, UsePath, UsePathTag,
  IdUsePath, PackageUsePath,
  PackageName, WorldItem, WorldItemTag, Import, Export, ExternKind,
  ExternKindTag, Id, Include, Field, Case, EnumCaseDef, FlagDef, Parser,
  Docs, AttributeTag,
} from './parser.zena';

/** A failure to encode: a construct the encoder cannot express yet. */
export class EncodeError extends Error {
  new(message: String) : super(message);
}

/**
 * A WIT type expression, parsed alone: wrapped in a one-alias
 * document so the ordinary parser reads it, then unwrapped. Names
 * stay syntactic — the caller resolves them against an interface.
 */
function parseTypeText(text: String): Type {
  let ast = Parser.parse(
      `package canon:payload;\ninterface t {\n  type p = ${text};\n}\n`);
  for (let item in ast.items) {
    if (item.tag != AstItemTag.Interface) { continue; }
    for (let ii in (item.interfaceDef as InterfaceDef).items) {
      if (ii.tag != InterfaceItemTag.TypeDef) { continue; }
      let td = ii.typeDef as TypeDef;
      if (td.tag == TypeDefTag.Alias) {
        return td.aliasType as Type;
      }
    }
  }
  throw new EncodeError(`cannot parse the canon type payload '${text}'`);
}

// Component binary section ids. They are not core wasm's — a component
// numbers its sections differently.
export let sectionCoreModule = 1;
export let sectionType = 7;
export let sectionAlias = 6;
export let sectionImport = 10;
export let sectionExport = 11;

/** The name a nested component imports the export `name` under: the
 * resource and the kind spelled out, as wit-component names them. */
function nestedFuncImportName(name: String) {
  if (name.startsWith("[constructor]")) {
    return "import-constructor-" + name.sliceBytes(13, name.length);
  }
  if (name.startsWith("[method]") || name.startsWith("[static]")) {
    let kind = name.sliceBytes(1, 7);
    let rest = name.sliceBytes(9, name.length);
    var out = `import-${kind}-`;
    for (var i = 0; i < rest.length; i += 1) {
      let c = rest.getByteAt(i);
      out = out + (if (c == 46) "-" else rest.sliceBytes(i, i + 1)); // '.'
    }
    return out;
  }
  return "import-func-" + name;
}

/**
 * One section of the component head, in emission order. The ids repeat —
 * a type section per instance type, an import section per import — which
 * the format allows and `wasm-tools` itself produces; interleaving is
 * what lets an alias name the import before it.
 */
export final class SectionPiece {
  id: i32;
  payload: ByteBuffer;
  new(this.id, this.payload);
}

/**
 * A value-type code: a local type index when `>= 0`, and a primitive's
 * opcode negated when `< 0`. The two need one representation because a
 * field or parameter holds either, and the sign is what keeps an index
 * of 0x73 distinct from `string`.
 */
function primCode(opcode: i32) {
  return 0 - opcode;
}

function writeValType(buf: ByteBuffer, code: i32) {
  if (code < 0) {
    buf.writeByte(0 - code);
  } else {
    // Signed on purpose: this position's grammar is
    // `typeidx | primvaltype`, and the primitives are the negative
    // SLEB128 space. An unsigned encoding of 64..127 would collide.
    buf.writeSLEB128(code);
  }
}

function writeName(buf: ByteBuffer, name: String) {
  buf.writeULEB128(name.length);
  for (var i = 0; i < name.length; i += 1) {
    buf.writeByte(name.getByteAt(i));
  }
}

/** An import or export name: the plain-name discriminant, then the name. */
function writeExternName(buf: ByteBuffer, name: String) {
  buf.writeByte(0x00);
  writeName(buf, name);
}

function primOpcodeOf(tag: TypeTag): i32 {
  if (tag == TypeTag.Bool) { return 0x7f; }
  if (tag == TypeTag.S8) { return 0x7e; }
  if (tag == TypeTag.U8) { return 0x7d; }
  if (tag == TypeTag.S16) { return 0x7c; }
  if (tag == TypeTag.U16) { return 0x7b; }
  if (tag == TypeTag.S32) { return 0x7a; }
  if (tag == TypeTag.U32) { return 0x79; }
  if (tag == TypeTag.S64) { return 0x78; }
  if (tag == TypeTag.U64) { return 0x77; }
  if (tag == TypeTag.F32) { return 0x76; }
  if (tag == TypeTag.F64) { return 0x75; }
  if (tag == TypeTag.Char) { return 0x74; }
  if (tag == TypeTag.String) { return 0x73; }
  return -1;
}

/**
 * Where a `use`d name comes from: the qualified name of the interface
 * that declares it, and the name it has there (a `use` may rename).
 */
final class UseHop {
  source: String;
  typeName: String;
  new(this.source, this.typeName);
}

/** One interface the document defines, under its import name. */
final class RegisteredInterface {
  /** The name the component imports it by: `ns:pkg/iface@version`. */
  qualifiedName: String;
  items: Array<InterfaceItem>;
  /**
   * The package the interface was declared in. A bare `use foo` from
   * inside it resolves against this package, not the document's main
   * one — nested packages have their own name spaces.
   */
  packageName: PackageName | null;
  new(this.qualifiedName, this.items, this.packageName = null);
}

/**
 * Where declarations land while one signature's types are encoded.
 *
 * An *instance* scope buffers instance declarations — `0x01` type,
 * `0x04` export — to become one instance type, and its indices are
 * local to it. The *component* scope (for a world-level function's
 * types) writes each type as a component-level type section instead,
 * and its indices are the component's. `#declareType` is the one place
 * that knows the difference.
 */
final class Scope {
  /** Buffered instance declarations; unused at component level. */
  decls = new ByteBuffer();
  var declCount = 0;
  var typeCount = 0;
  /** WIT type name → the local index its *export* created. */
  named = new HashMap<String, i32>();
  /**
   * The named indices that are resources. A resource name in value
   * position means `own` of it — `open: func() -> bucket` returns a
   * handle — so `#encodeType` has to know which lookups to wrap, and
   * a `use`d resource is still one.
   */
  resourceIndices = new HashMap<i32, boolean>();
  /** Structural key of an anonymous type → its index here. */
  anon = new HashMap<String, i32>();
  /**
   * The interface's type definitions not encoded yet, by name: a
   * reference to one encodes it on the spot, so an interface may
   * declare its types in any order — upstream WASI does, and the
   * encoding's own order is first use.
   */
  pending = new HashMap<String, TypeDef>();
  var atComponentLevel = false;
  /**
   * Component-level only: the interface whose declarations resolve
   * named types this scope meets, each alias-exported from the
   * imported instance on first use. Set for a canon builtin's type —
   * a `future<result<option<trailers>, error-code>>` names the
   * interface's types from outside any instance scope.
   */
  var aliasSource: RegisteredInterface | null = null;
  /**
   * Set while encoding into a nested component (an exported
   * interface's): declared types go to its sections and count in its
   * own index space, and a named type of the interface is imported
   * into it on first use rather than aliased.
   */
  var nested: NestedComponent | null = null;
  /**
   * The nested component's hooks, installed by its encoder: where a
   * declared type goes, and how a named type is met. Closures rather
   * than calls on `nested`, because a program that never builds a
   * nested component (the encoder's own round-trip tool) never
   * constructs the class, and the compiler refuses a method call on
   * a class it never constructed even on a path that cannot run
   * (issue #447); a closure that is never created reaches nothing.
   */
  var nestedDeclare: ((body: ByteBuffer) => void) | null = null;
  var nestedNamed: ((name: String) => i32) | null = null;

}

/**
 * A type a nested component imports from the enclosing one: the
 * import's name, and the enclosing component's type index the
 * instantiation supplies for it.
 */
export final class NestedTypeImport {
  name: String;
  outerIndex: i32;
  new(this.name, this.outerIndex);
}

/**
 * An exported interface realized as a nested component, the shape an
 * exported resource needs: a component's own exports name a resource
 * (`export "surface" (type $r)`), and a `[method]surface.size` export
 * is validated against the names in that context, which an instance
 * built from a bag of exports never has. The nested component imports
 * each resource as a subtype of `resource` and each non-resource type
 * as `eq` of a local copy, imports the enclosing component's lifted
 * functions at types naming those, exports the resources and fresh
 * copies of the other types under their names, and exports each
 * function with a type naming the exported ones — what wit-component
 * emits. `funcImports` are the function import names, one per export
 * name the encoding was asked for, in that order.
 */
export final class NestedExport {
  bytes = new ByteBuffer();
  typeImports = new GrowableArray<NestedTypeImport>();
  funcImports = new GrowableArray<String>();

}

/** A nested component under construction. */
final class NestedComponent {
  out: NestedExport;
  var funcCount = 0;
  /** The interface's own non-resource types imported so far, to
   * export again once the resources have their names. */
  ownTypes = new GrowableArray<String>();
  /** Whether the export phase has begun: a named type met now is
   * exported as a fresh copy rather than imported. */
  var exporting = false;
  new(this.out);

  section(id: i32, payload: ByteBuffer): void {
    this.out.bytes.writeByte(id);
    this.out.bytes.writeULEB128(payload.length);
    this.out.bytes.writeBuffer(payload);
  }
}

/**
 * A resource the program provides, in the order its type was encoded:
 * the k-th one's destructor is core function k. The emitter keeps that
 * promise with a shim core module it instantiates before anything
 * else — a table of function references and one trampoline per slot,
 * aliased as the first core functions — and fills the table with the
 * program's destructor exports once the program instance exists. The
 * indirection is what lets the resource type name a destructor that
 * lives in an instance which cannot exist yet: the program's core
 * module imports `resource.new` for the type, so the type comes first.
 */
export final class DtorSlot {
  qualified: String;
  name: String;
  new(this.qualified, this.name);
}

/** What `encodeWorld` produced. */
/** One type an exported interface declares itself: its name in the
 * interface, and the component-level type index it was encoded at. */
export final class ExportedTypeIndex {
  name: String;
  index: i32;
  new(this.name, this.index);
}

export final class EncodedWorld {
  /** The component-head sections, in order. */
  pieces = new GrowableArray<SectionPiece>();
  /**
   * The types each exported interface declares itself, by the
   * interface's qualified name, in encoding order. Encoded at
   * component level as a function type of the interface first names
   * them; the exported instance exports each under its name, so the
   * interface reads back with its own types.
   */
  exportedTypes = new HashMap<String, GrowableArray<ExportedTypeIndex>>();
  /** The program's resources with a destructor slot each (`DtorSlot`). */
  dtorSlots = new GrowableArray<DtorSlot>();
  /** How many component-level types the pieces defined. */
  var typeCount = 0;
  /** How many instances the pieces imported. */
  var instanceCount = 0;
  /** How many component-level functions the pieces imported. */
  var funcImportCount = 0;
  /**
   * Each imported interface's component-level instance index, by its
   * qualified name. Interfaces are imported in dependency order, not
   * request order, so a consumer aliasing functions out of an instance
   * looks the index up rather than assuming it.
   */
  instanceIndices = new HashMap<String, i32>();
  /** World exports the encoding skipped, for the caller to report. */
  skippedExports = new GrowableArray<String>();

}

export final class ComponentTypeEncoder {
  #ast: Ast;
  #result = new EncodedWorld();
  /** Everything importable by qualified name, main package and nested. */
  #interfaces = new GrowableArray<RegisteredInterface>();
  /** Qualified interface name → component-level instance index. */
  #instanceIndex = new HashMap<String, i32>();
  /**
   * `qualifiedInterface + '#' + typeName` → the component-level type
   * index its `alias export` created. One alias serves every interface
   * that uses the type.
   */
  #aliasedTypes = new HashMap<String, i32>();

  new(ast: Ast) : #ast = ast {
    this.#registerPackage(ast.packageName, ast.items);
    for (let nested in ast.nestedPackages) {
      this.#registerPackage(nested.name, nested.items);
    }
  }

  #registerPackage(pkgName: PackageName | null, items: Array<AstItem>): void {
    for (let item in items) {
      if (item.tag == AstItemTag.Interface) {
        let def = item.interfaceDef as InterfaceDef;
        this.#interfaces.push(new RegisteredInterface(
            qualifiedInterfaceName(pkgName, def.name.name), def.items,
            pkgName));
      }
    }
  }

  /**
   * Encode the world's imports. Interfaces are imported in first-use
   * order with their `use` dependencies ahead of them — WIT implies the
   * import of anything a used type comes from, so a dependency absent
   * from the world's own list still gets an instance. An `include`
   * brings the included world's imports and exports
   * (expandedWorldItems).
   */
  encodeWorld(worldName: String): EncodedWorld {
    let world = this.#findWorld(worldName);
    for (let item in expandedWorldItems(this.#ast, world)) {
      if (item.tag == WorldItemTag.Import) {
        this.#encodeWorldImport((item.importItem as Import).kind);
      } else if (item.tag == WorldItemTag.Export) {
        this.#result.skippedExports.push(externName(
            (item.exportItem as Export).kind));
      } else if (item.tag == WorldItemTag.Use) {
        throw new EncodeError("world-level `use` is not encodable yet");
      } else if (item.tag == WorldItemTag.TypeDef) {
        throw new EncodeError(
            "world-level type definitions are not encodable yet");
      } else {
        throw new EncodeError("world `include` is not encodable yet");
      }
    }
    return this.#result;
  }

  #encodeWorldImport(kind: ExternKind): void {
    if (kind.tag == ExternKindTag.Path) {
      this.#importInterface(this.#resolveInterface(kind.path as UsePath));
    } else if (kind.tag == ExternKindTag.Func) {
      this.#importWorldFunc((kind.name as Id).name, kind.funcDef as Func);
    } else {
      // An inline interface: the same encoding, imported under the
      // plain name its declaration gave it.
      this.#importNamedInterface(new RegisteredInterface(
          (kind.name as Id).name, kind.items as GrowableArray<InterfaceItem>));
    }
  }

  /**
   * A world-level function import: its types live at component level,
   * each in a type section of its own, then the import names the
   * functype. Only structural types can appear here — a named type
   * would have arrived through world-level `use` or a world type
   * definition, both rejected before this runs.
   */
  #importWorldFunc(name: String, func: Func): void {
    let scope = new Scope();
    scope.atComponentLevel = true;
    scope.typeCount = this.#result.typeCount;
    let funcType = this.#encodeFuncType(scope, func, -1, func.isAsync);
    let imp = new ByteBuffer();
    imp.writeULEB128(1);
    writeExternName(imp, name);
    imp.writeByte(0x01); // externdesc: func
    imp.writeULEB128(funcType);
    this.#result.pieces.push(new SectionPiece(sectionImport, imp));
    this.#result.funcImportCount += 1;
  }

  #resolveInterface(
    path: UsePath,
    contextPackage: PackageName | null = null
  ): RegisteredInterface {
    let qualified = if (path.tag == UsePathTag.Id) {
      // A bare name resolves within the package the `use` sits in;
      // only a top-level world's imports resolve against the main one.
      qualifiedInterfaceName(
          contextPackage ?? this.#ast.packageName,
          (path.id as Id).name)
    } else {
      qualifiedInterfaceName(path.packageId, (path.name as Id).name)
    };
    for (let r in this.#interfaces) {
      if (r.qualifiedName == qualified) {
        return r;
      }
    }
    throw new EncodeError("interface '" + qualified +
        "' is not defined in this document; cross-document " +
        "dependencies are not resolvable yet");
  }

  #importInterface(reg: RegisteredInterface): void {
    if (this.#instanceIndex.has(reg.qualifiedName)) {
      return;
    }
    // Dependencies first: an `alias export` can only name an instance
    // that is already imported.
    for (let item in reg.items) {
      if (item.tag == InterfaceItemTag.Use) {
        this.#importInterface(this.#resolveInterface(
            (item.use as Use).from, reg.packageName));
      }
    }
    this.#importNamedInterface(reg);
  }

  #importNamedInterface(reg: RegisteredInterface): void {
    let scope = new Scope();
    for (let item in reg.items) {
      if (item.tag == InterfaceItemTag.TypeDef) {
        let td = item.typeDef as TypeDef;
        scope.pending[td.name.name] = td;
      }
    }
    for (let item in reg.items) {
      if (item.tag == InterfaceItemTag.Use) {
        this.#encodeUse(scope, item.use as Use, reg.packageName);
      } else if (item.tag == InterfaceItemTag.TypeDef) {
        let td = item.typeDef as TypeDef;
        // Unless a reference already encoded it.
        if (scope.pending.has(td.name.name)) {
          this.#encodeTypeDef(scope, td);
        }
      } else {
        this.#encodeInterfaceFunc(scope, item.func as NamedFunc, "", -1);
      }
    }

    let types = new ByteBuffer();
    types.writeULEB128(1);
    types.writeByte(0x42); // instance type
    types.writeULEB128(scope.declCount);
    types.writeBuffer(scope.decls);
    this.#result.pieces.push(new SectionPiece(sectionType, types));
    let instanceTypeIndex = this.#result.typeCount;
    this.#result.typeCount += 1;

    let imp = new ByteBuffer();
    imp.writeULEB128(1);
    writeExternName(imp, reg.qualifiedName);
    imp.writeByte(0x05); // externdesc: instance
    imp.writeULEB128(instanceTypeIndex);
    this.#result.pieces.push(new SectionPiece(sectionImport, imp));
    this.#instanceIndex[reg.qualifiedName] = this.#result.instanceCount;
    this.#result.instanceIndices[reg.qualifiedName] =
        this.#result.instanceCount;
    this.#result.instanceCount += 1;
  }

  /**
   * A `use`: each named type is aliased out of its source instance at
   * component level (once, however many interfaces use it), aliased
   * back in through `outer`, and re-exported under its local name —
   * which may differ, `use` renames.
   */
  #encodeUse(
    scope: Scope,
    use: Use,
    contextPackage: PackageName | null
  ): void {
    let source = this.#resolveInterface(use.from, contextPackage);
    for (let n in use.names) {
      let componentIndex =
          this.#usedTypeIndex(new UseHop(source.qualifiedName, n.name.name));
      scope.decls.writeByte(0x02); // instancedecl: alias
      scope.decls.writeByte(0x03); // sort: type
      scope.decls.writeByte(0x02); // target: outer
      scope.decls.writeULEB128(1); // count 1: the enclosing component
      scope.decls.writeULEB128(componentIndex);
      scope.declCount += 1;
      let inner = scope.typeCount;
      scope.typeCount += 1;

      let asName = n.asName;
      let localName = asName?.name ?? n.name.name;
      let exported = this.#exportType(scope, localName, inner);
      scope.named[localName] = exported;
      if (this.#isResource(source, n.name.name)) {
        scope.resourceIndices[exported] = true;
      }
    }
  }

  /**
   * Whether `name` in `reg` is a resource — directly, through a `use`,
   * or through a `type` alias of either. Resource-ness survives every
   * hop, and it decides whether a value-position mention is a handle.
   */
  /**
   * The interface `reg` `use`s `name` from, and the name there, or
   * null when `reg` does not `use` it.
   */
  #useSourceOf(reg: RegisteredInterface, name: String): UseHop | null {
    for (let item in reg.items) {
      if (item.tag != InterfaceItemTag.Use) { continue; }
      let use = item.use as Use;
      for (let n in use.names) {
        let asName = n.asName;
        let localName =
            asName?.name ?? n.name.name;
        if (localName == name) {
          let source = this.#resolveInterface(use.from, reg.packageName);
          return new UseHop(source.qualifiedName, n.name.name);
        }
      }
    }
    return null;
  }

  #isResource(reg: RegisteredInterface, name: String): boolean {
    for (let item in reg.items) {
      if (item.tag == InterfaceItemTag.TypeDef) {
        let td = item.typeDef as TypeDef;
        if (td.name.name == name) {
          if (td.tag == TypeDefTag.Resource) {
            return true;
          }
          if (td.tag == TypeDefTag.Alias) {
            let target = td.aliasType as Type;
            if (target.tag == TypeTag.Name) {
              return this.#isResource(reg, (target.name as Id).name);
            }
          }
          return false;
        }
      } else if (item.tag == InterfaceItemTag.Use) {
        let use = item.use as Use;
        for (let n in use.names) {
          let asName = n.asName;
          let localName =
              asName?.name ?? n.name.name;
          if (localName == name) {
            return this.#isResource(
                this.#resolveInterface(use.from, reg.packageName),
                n.name.name);
          }
        }
      }
    }
    return false;
  }

  /**
   * The component-level type index of `typeName` exported by an
   * already-imported interface, alias-exporting it on first use.
   * Public for the canon builtins: `resource.drop` takes the imported
   * resource's own (nominal) type as its immediate, which only an
   * alias can name.
   */
  aliasResourceType(qualifiedInterface: String, typeName: String): i32 {
    let reg = this.#findRegistered(qualifiedInterface);
    if (reg == null || !this.#isResource(
        reg, typeName)) {
      throw new EncodeError("'" + typeName + "' is not a resource of '" +
          qualifiedInterface + "'");
    }
    if (!this.#instanceIndex.has(qualifiedInterface)) {
      // No instance to alias from: the interface is exported, and the
      // resource is the program's own — `resource.new` and
      // `resource.rep` name its component-level type.
      return this.#encodeExportedOwnType(reg,
          typeName);
    }
    return this.#aliasTypeExport(qualifiedInterface, typeName);
  }

  /**
   * The component-level type index of `future<payloadText>`, the
   * payload parsed as WIT against `qualifiedInterface`'s declarations
   * — named types alias-exported from the imported instance on first
   * use, or, for an exported interface, from the imported source its
   * `use` names. Public for the canon builtins: the future.* family's
   * canon entry carries the future's own component type, and a payload
   * like `result<option<trailers>, error-code>` names the interface's
   * types from outside any instance scope. An empty `payloadText` is
   * the bare `future`; an empty `qualifiedInterface` is a world-level
   * function's future, whose payload is structural.
   */
  aliasFutureType(qualifiedInterface: String, payloadText: String): i32 {
    return this.#aliasEndType(0x65, "future", qualifiedInterface,
        payloadText);
  }

  /**
   * The component-level type index of `stream<elementText>`, the
   * element parsed against `qualifiedInterface`'s declarations the
   * way a future's payload is. Public for the canon builtins: the
   * stream.* family's canon entry carries the stream's own type.
   */
  aliasStreamType(qualifiedInterface: String, elementText: String): i32 {
    return this.#aliasEndType(0x66, "stream", qualifiedInterface,
        elementText);
  }

  /** `future<p>` (0x65) or `stream<e>` (0x66) at component level,
   * memoized per interface and payload spelling. */
  #aliasEndType(opcode: i32, head: String, qualifiedInterface: String,
      payloadText: String): i32 {
    let key = `${qualifiedInterface}#${head}<${payloadText}>`;
    if (let (true, existing) = this.#aliasedTypes.get(key)) {
      return existing;
    }
    let scope = new Scope();
    scope.atComponentLevel = true;
    scope.typeCount = this.#result.typeCount;
    if (qualifiedInterface != "") {
      let reg = this.#findRegistered(qualifiedInterface);
      if (reg == null) {
        throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
      }
      scope.aliasSource = reg;
    }
    let inner = if (payloadText != "") {
      this.#encodeType(scope, parseTypeText(payloadText))
    } else {
      -1
    };
    let body = new ByteBuffer();
    body.writeByte(opcode);
    if (payloadText != "") {
      body.writeByte(0x01);
      writeValType(body, inner);
    } else {
      body.writeByte(0x00);
    }
    let index = this.#declareType(scope, body);
    this.#aliasedTypes[key] = index;
    return index;
  }

  /**
   * The component-level valtype — a primitive's code, or a type
   * index — of the WIT type `typeText`. Parsed against
   * `qualifiedInterface`'s declarations when one is named, its named
   * types alias-exported from the imported instance on first use;
   * at the component's own level when the name is empty, where only
   * structural types can appear. Public for the canon builtins: a
   * typed `task.return` carries the result type of the export it
   * returns for.
   */
  encodeTypeText(qualifiedInterface: String, typeText: String): i32 {
    let key = `${qualifiedInterface}#type:${typeText}`;
    if (let (true, existing) = this.#aliasedTypes.get(key)) {
      return existing;
    }
    let scope = new Scope();
    scope.atComponentLevel = true;
    scope.typeCount = this.#result.typeCount;
    if (qualifiedInterface != "") {
      // Imported or exported: an exported interface's named types
      // reach it through `use`, and `#namedIndex` follows the use to
      // the imported source.
      let reg = this.#findRegistered(qualifiedInterface);
      if (reg == null) {
        throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
      }
      scope.aliasSource = reg;
    }
    let code = this.#encodeType(scope, parseTypeText(typeText));
    this.#aliasedTypes[key] = code;
    return code;
  }

  /**
   * The component-level function type of `funcName` in the exported
   * interface `qualifiedInterface`, for the lift of the core function
   * implementing it. Its named types come through the interface's
   * `use`s, alias-exported from the imported sources; a type the
   * exported interface declares itself is not encodable yet.
   */
  encodeExportedInterfaceFuncType(
    qualifiedInterface: String,
    funcName: String
  ): i32 {
    let reg = this.#findRegistered(qualifiedInterface);
    if (reg == null) {
      throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
    }
    for (let item in reg.items) {
      if (item.tag != InterfaceItemTag.Func) { continue; }
      let nf = item.func as NamedFunc;
      if (nf.name.name != funcName) { continue; }
      let scope = new Scope();
      scope.atComponentLevel = true;
      scope.typeCount = this.#result.typeCount;
      scope.aliasSource = reg;
      return this.#encodeFuncType(scope, nf.func, -1, nf.func.isAsync);
    }
    // A resource's function, exported under its mangled name: the
    // program's resource type is encoded (or found) at component
    // level, and a method's `self` is a borrow of it.
    let found = resourceFuncNamed(reg.items, funcName);
    if (found != null) {
      let rf = found.rf;
      let scope = new Scope();
      scope.atComponentLevel = true;
      scope.typeCount = this.#result.typeCount;
      scope.aliasSource = reg;
      let resourceIndex = this.#namedIndex(scope,
          found.resourceName);
      if (rf.tag == ResourceFuncTag.Constructor) {
        return this.#constructorFuncType(scope, rf.func.func, resourceIndex);
      }
      if (rf.tag == ResourceFuncTag.Method) {
        let borrowIndex = this.#handleType(scope, 0x68, resourceIndex);
        return this.#encodeFuncType(scope, rf.func.func, borrowIndex,
            rf.func.func.isAsync);
      }
      return this.#encodeFuncType(scope, rf.func.func, -1,
          rf.func.func.isAsync);
    }
    throw new EncodeError("'" + qualifiedInterface +
        "' declares no function '" + funcName + "'");
  }

  /** Whether the interface `qualified` declares a resource of its own. */
  interfaceDeclaresResource(qualified: String): boolean {
    let reg = this.#findRegistered(qualified);
    if (reg == null) {
      return false;
    }
    for (let item in reg.items) {
      if (item.tag == InterfaceItemTag.TypeDef &&
          (item.typeDef as TypeDef).tag == TypeDefTag.Resource) {
        return true;
      }
    }
    return false;
  }

  /**
   * The nested component realizing the exported interface
   * `qualifiedInterface` (see `NestedExport`), with the functions the
   * program exports under `exportNames` — every function of the
   * interface, in the order the emitter lifts them.
   */
  encodeExportedInterfaceComponent(qualifiedInterface: String,
      exportNames: Array<String>): NestedExport {
    let regOpt = this.#findRegistered(qualifiedInterface);
    if (regOpt == null) {
      throw new EncodeError(`'${qualifiedInterface}' is not a known interface`);
    }
    let reg = regOpt;
    let out = new NestedExport();
    let nested = new NestedComponent(out);
    out.bytes.writeU32(0x6D736100); // \0asm
    out.bytes.writeU32(0x0001000D); // version 0x0d, layer 1: a component
    let scope = new Scope();
    scope.nested = nested;
    scope.aliasSource = reg;
    scope.nestedDeclare = (body: ByteBuffer) => {
      let section = new ByteBuffer();
      section.writeULEB128(1);
      section.writeBuffer(body);
      nested.section(sectionType, section);
    };
    scope.nestedNamed = (name: String) =>
        this.#nestedNamedIndex(scope, name);

    // 1. Every resource the interface declares or `use`s, imported as
    // a subtype of `resource`; the enclosing component's own resource
    // type, or its alias of an imported instance's, instantiates it.
    let resources = new GrowableArray<String>();
    for (let item in reg.items) {
      if (item.tag == InterfaceItemTag.TypeDef) {
        let td = item.typeDef as TypeDef;
        if (td.tag == TypeDefTag.Resource) {
          resources.push(td.name.name);
        }
      } else if (item.tag == InterfaceItemTag.Use) {
        for (let n in (item.use as Use).names) {
          let asName = n.asName;
          let localName =
              asName?.name ?? n.name.name;
          if (this.#isResource(reg, localName)) {
            resources.push(localName);
          }
        }
      }
    }
    for (let r in resources) {
      let hop = this.#useSourceOf(reg, r);
      let outerIndex = if (hop == null) {
        this.#encodeExportedOwnType(reg, r)
      } else {
        this.#usedTypeIndex(hop)
      };
      let imp = new ByteBuffer();
      imp.writeULEB128(1);
      writeExternName(imp, "import-type-" + r);
      imp.writeByte(0x03); // externdesc: type
      imp.writeByte(0x01); // typebound: sub resource
      nested.section(sectionImport, imp);
      let index = scope.typeCount;
      scope.typeCount += 1;
      scope.named[r] = index;
      scope.resourceIndices[index] = true;
      out.typeImports.push(new NestedTypeImport("import-type-" + r, outerIndex));
    }

    // 2. The functions, imported at types naming the imported
    // resources (an import may name only imported types).
    for (let name in exportNames) {
      let typeIndex = this.#nestedFuncType(scope, reg, name);
      let importName = nestedFuncImportName(name);
      let imp = new ByteBuffer();
      imp.writeULEB128(1);
      writeExternName(imp, importName);
      imp.writeByte(0x01); // externdesc: func
      imp.writeULEB128(typeIndex);
      nested.section(sectionImport, imp);
      out.funcImports.push(importName);
      nested.funcCount += 1;
    }

    // 3. The exports: the resources under their names — which is what
    // names them for the method-style exports — then fresh copies of
    // the interface's other types, then each function at a type naming
    // the exported ones, ascribed on the export.
    nested.exporting = true;
    scope.anon.clear();
    for (let name in nested.ownTypes) {
      scope.named.delete(name);
    }
    for (let r in resources) {
      let imported = scope.named[r];
      let index = this.#nestedExportType(scope, r, imported);
      scope.named[r] = index;
      scope.resourceIndices[index] = true;
    }
    let ownTypes = new GrowableArray<String>();
    for (let name in nested.ownTypes) {
      ownTypes.push(name);
    }
    for (let name in ownTypes) {
      this.#namedIndex(scope, name);
    }
    for (var i = 0; i < exportNames.length; i += 1) {
      let ascribed = this.#nestedFuncType(scope, reg, exportNames[i]);
      let exp = new ByteBuffer();
      exp.writeULEB128(1);
      writeExternName(exp, exportNames[i]);
      exp.writeByte(0x01); // sort: func
      exp.writeULEB128(i);
      exp.writeByte(0x01); // an ascribed type follows
      exp.writeByte(0x01); // externdesc: func
      exp.writeULEB128(ascribed);
      nested.section(sectionExport, exp);
    }
    return out;
  }

  /** Exports nested type `index` under `name`; the export's own index. */
  #nestedExportType(scope: Scope, name: String, index: i32): i32 {
    let nested = scope.nested as NestedComponent;
    let exp = new ByteBuffer();
    exp.writeULEB128(1);
    writeExternName(exp, name);
    exp.writeByte(0x03); // sort: type
    exp.writeULEB128(index);
    exp.writeByte(0x00); // no ascribed type
    nested.section(sectionExport, exp);
    let exported = scope.typeCount;
    scope.typeCount += 1;
    return exported;
  }

  /**
   * A named non-resource type met inside a nested component: its
   * structure declared there, resolved against the interface that
   * declares it, then imported as `eq` of that declaration (the
   * enclosing component's type instantiates it) — or, in the export
   * phase, exported as a fresh copy under its name.
   */
  #nestedNamedIndex(scope: Scope, name: String): i32 {
    let nested = scope.nested as NestedComponent;
    let reg = scope.aliasSource as RegisteredInterface;
    if (this.#isResource(reg, name)) {
      throw new EncodeError("resource '" + name + "' of '" +
          reg.qualifiedName + "' was not imported into its exported instance");
    }
    var owner = reg;
    var tdName = name;
    var outerIndex = -1;
    let hop = this.#useSourceOf(reg, name);
    if (hop == null) {
      if (!this.#declaresType(reg, name)) {
        throw new EncodeError("'" + reg.qualifiedName +
            "' declares no type '" + name + "'");
      }
      outerIndex = this.#encodeExportedOwnType(reg, name);
    } else {
      let h = hop;
      let source = this.#findRegistered(h.source);
      if (source == null) {
        throw new EncodeError(`'${h.source}' is not a known interface`);
      }
      owner = source;
      tdName = h.typeName;
      outerIndex = this.#usedTypeIndex(h);
    }
    var found: TypeDef | null = null;
    for (let item in owner.items) {
      if (item.tag != InterfaceItemTag.TypeDef) { continue; }
      let td = item.typeDef as TypeDef;
      if (td.name.name == tdName) { found = td; }
    }
    if (found == null) {
      throw new EncodeError("'" + owner.qualifiedName +
          "' declares no type '" + tdName + "'");
    }
    let td = found;
    let savedSource = scope.aliasSource;
    scope.aliasSource = owner;
    var local = -1;
    if (td.tag == TypeDefTag.Alias) {
      let target = td.aliasType as Type;
      if (target.tag == TypeTag.Name) {
        local = this.#namedIndex(scope, (target.name as Id).name);
      } else {
        let encoded = this.#encodeType(scope, target);
        if (encoded < 0) {
          let body = new ByteBuffer();
          body.writeByte(0 - encoded);
          local = this.#declareType(scope, body);
        } else {
          local = encoded;
        }
      }
    } else {
      local = this.#encodeTypeBody(scope, td);
    }
    scope.aliasSource = savedSource;
    if (nested.exporting) {
      let index = this.#nestedExportType(scope, name, local);
      scope.named[name] = index;
      return index;
    }
    let imp = new ByteBuffer();
    imp.writeULEB128(1);
    writeExternName(imp, "import-type-" + name);
    imp.writeByte(0x03); // externdesc: type
    imp.writeByte(0x00); // typebound: eq
    imp.writeULEB128(local);
    nested.section(sectionImport, imp);
    let index = scope.typeCount;
    scope.typeCount += 1;
    scope.named[name] = index;
    nested.out.typeImports.push(
        new NestedTypeImport("import-type-" + name, outerIndex));
    if (hop == null) {
      nested.ownTypes.push(name);
    }
    return index;
  }

  /**
   * The function type of the export `name` of `reg` in `scope` — a
   * free function's, or a resource function's found by its mangled
   * name, with a constructor's implicit `own` result and a method's
   * `self` borrow.
   */
  #nestedFuncType(scope: Scope, reg: RegisteredInterface,
      name: String): i32 {
    for (let item in reg.items) {
      if (item.tag != InterfaceItemTag.Func) { continue; }
      let nf = item.func as NamedFunc;
      if (nf.name.name == name) {
        return this.#encodeFuncType(scope, nf.func, -1, nf.func.isAsync);
      }
    }
    let found = resourceFuncNamed(reg.items, name);
    if (found == null) {
      throw new EncodeError("'" + reg.qualifiedName +
          "' declares no function '" + name + "'");
    }
    let rf = found.rf;
    let resourceIndex = scope.named[found.resourceName];
    if (rf.tag == ResourceFuncTag.Constructor) {
      return this.#constructorFuncType(scope, rf.func.func, resourceIndex);
    }
    if (rf.tag == ResourceFuncTag.Method) {
      let borrowIndex = this.#handleType(scope, 0x68, resourceIndex);
      return this.#encodeFuncType(scope, rf.func.func, borrowIndex,
          rf.func.func.isAsync);
    }
    return this.#encodeFuncType(scope, rf.func.func, -1, rf.func.func.isAsync);
  }

  /** A constructor's function type: its parameters, and `own` of the
   * resource as the result. */
  #constructorFuncType(scope: Scope, func: Func, resourceIndex: i32): i32 {
    let ownIndex = this.#handleType(scope, 0x69, resourceIndex);
    let paramCodes = new GrowableArray<i32>();
    for (let p in func.params) {
      paramCodes.push(this.#encodeType(scope, p.type));
    }
    let body = new ByteBuffer();
    body.writeByte(0x40);
    body.writeULEB128(func.params.length);
    for (var i = 0; i < func.params.length; i += 1) {
      writeName(body, func.params[i].name.name);
      writeValType(body, paramCodes[i]);
    }
    body.writeByte(0x00);
    writeValType(body, ownIndex);
    return this.#declareType(scope, body);
  }

  /**
   * The component-level function type of the world's function export
   * `exportName`, for the lift of the core function implementing it.
   * Its types are structural, like a world-level import's: a named
   * type would need world-level `use` encoding.
   */
  encodeWorldExportFuncType(worldName: String, exportName: String): i32 {
    let world = this.#findWorld(worldName);
    for (let item in expandedWorldItems(this.#ast, world)) {
      if (item.tag != WorldItemTag.Export) { continue; }
      let kind = (item.exportItem as Export).kind;
      if (kind.tag != ExternKindTag.Func) { continue; }
      if ((kind.name as Id).name != exportName) { continue; }
      let func = kind.funcDef as Func;
      let scope = new Scope();
      scope.atComponentLevel = true;
      scope.typeCount = this.#result.typeCount;
      return this.#encodeFuncType(scope, func, -1, func.isAsync);
    }
    throw new EncodeError("world '" + worldName +
        "' exports no function named '" + exportName + "'");
  }

  #findWorld(worldName: String): WorldDef {
    for (let item in this.#ast.items) {
      if (item.tag == AstItemTag.World) {
        let def = item.worldDef as WorldDef;
        if (def.name.name == worldName) {
          return def;
        }
      }
    }
    throw new EncodeError(
        `no world named '${worldName}' in this document`);
  }

  /** The registered interface named `qualified`, or null. */
  #findRegistered(qualified: String): RegisteredInterface | null {
    for (let reg in this.#interfaces) {
      if (reg.qualifiedName == qualified) {
        return reg;
      }
    }
    return null;
  }

  /**
   * The component-level type index of the type a `use` hop names: an
   * alias out of the source's instance when the source is imported,
   * or, when the source is an exported interface, its own declaration
   * at component level (`#encodeExportedOwnType`), following a further
   * `use` of the source's first. An exported interface may `use` a
   * type another exported interface declares, as a plugin kind uses
   * the resources of the views it vends.
   */
  #usedTypeIndex(hop: UseHop): i32 {
    if (this.#instanceIndex.has(hop.source)) {
      return this.#aliasTypeExport(hop.source, hop.typeName);
    }
    let source = this.#findRegistered(hop.source);
    if (source == null) {
      throw new EncodeError(`'${hop.source}' is not a known interface`);
    }
    let further = this.#useSourceOf(source, hop.typeName);
    if (further != null) {
      return this.#usedTypeIndex(further);
    }
    return this.#encodeExportedOwnType(source, hop.typeName);
  }

  #aliasTypeExport(qualifiedInterface: String, typeName: String): i32 {
    let key = `${qualifiedInterface}#${typeName}`;
    if (let (true, existing) = this.#aliasedTypes.get(key)) {
      return existing;
    }
    if (!this.#instanceIndex.has(qualifiedInterface)) {
      throw new EncodeError("'" + qualifiedInterface +
          "' is not imported yet, so nothing can use its types");
    }
    let alias = new ByteBuffer();
    alias.writeULEB128(1);
    alias.writeByte(0x03); // sort: type
    alias.writeByte(0x00); // target: instance export
    alias.writeULEB128(this.#instanceIndex[qualifiedInterface]);
    writeName(alias, typeName);
    this.#result.pieces.push(new SectionPiece(sectionAlias, alias));
    let index = this.#result.typeCount;
    this.#result.typeCount += 1;
    this.#aliasedTypes[key] = index;
    return index;
  }

  /** Export local type `index` under `name`; the export's own index. */
  #exportType(scope: Scope, name: String, index: i32): i32 {
    scope.decls.writeByte(0x04); // instancedecl: export
    writeExternName(scope.decls, name);
    scope.decls.writeByte(0x03); // externdesc: type
    scope.decls.writeByte(0x00); // typebound: eq
    scope.decls.writeULEB128(index);
    scope.declCount += 1;
    let exported = scope.typeCount;
    scope.typeCount += 1;
    return exported;
  }

  /** Declare an anonymous type from `body`; the index it gets. */
  #declareType(scope: Scope, body: ByteBuffer): i32 {
    let nestedDeclare = scope.nestedDeclare;
    if (nestedDeclare != null) {
      nestedDeclare(body);
    } else if (scope.atComponentLevel) {
      let section = new ByteBuffer();
      section.writeULEB128(1);
      section.writeBuffer(body);
      this.#result.pieces.push(new SectionPiece(sectionType, section));
      this.#result.typeCount += 1;
    } else {
      scope.decls.writeByte(0x01); // instancedecl: type
      scope.decls.writeBuffer(body);
      scope.declCount += 1;
    }
    let index = scope.typeCount;
    scope.typeCount += 1;
    return index;
  }

  #encodeTypeDef(scope: Scope, td: TypeDef): void {
    let name = td.name.name;
    scope.pending.delete(name);
    if (td.tag == TypeDefTag.Resource) {
      // A resource has no structure to declare — the export itself is
      // the declaration, and `sub resource` is its bound.
      scope.decls.writeByte(0x04);
      writeExternName(scope.decls, name);
      scope.decls.writeByte(0x03);
      scope.decls.writeByte(0x01); // typebound: sub resource
      scope.declCount += 1;
      let resourceIndex = scope.typeCount;
      scope.typeCount += 1;
      scope.named[name] = resourceIndex;
      scope.resourceIndices[resourceIndex] = true;
      for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
        this.#encodeResourceFunc(scope, rf, name, resourceIndex);
      }
      return;
    }

    var code = 0;
    if (td.tag == TypeDefTag.Record || td.tag == TypeDefTag.Variant ||
        td.tag == TypeDefTag.Enum || td.tag == TypeDefTag.Flags) {
      code = this.#encodeTypeBody(scope, td);
    } else {
      // `type name = t`: encode the target, and export an index for it.
      // A primitive target still needs a declared type to bound the
      // export to — `eq` takes an index, not an opcode. A named target
      // is looked up raw so that `type b = bucket` aliases the resource
      // itself rather than an `own` of it.
      let target = td.aliasType as Type;
      var isResource = false;
      if (target.tag == TypeTag.Name) {
        code = this.#namedIndex(scope, (target.name as Id).name);
        isResource = scope.resourceIndices.has(code);
      } else {
        let encoded = this.#encodeType(scope, target);
        if (encoded < 0) {
          let body = new ByteBuffer();
          body.writeByte(0 - encoded);
          code = this.#declareType(scope, body);
        } else {
          code = encoded;
        }
      }
      let exportedAlias = this.#exportType(scope, name, code);
      scope.named[name] = exportedAlias;
      if (isResource) {
        scope.resourceIndices[exportedAlias] = true;
      }
      return;
    }
    scope.named[name] = this.#exportType(scope, name, code);
  }

  /** The declared index of a record, variant, enum or flags body in
   * `scope`, its parts encoded first. */
  #encodeTypeBody(scope: Scope, td: TypeDef): i32 {
    var code = 0;
    if (td.tag == TypeDefTag.Record) {
      let fields = td.fields as GrowableArray<Field>;
      let fieldCodes = new GrowableArray<i32>();
      for (let f in fields) {
        fieldCodes.push(this.#encodeType(scope, f.type));
      }
      let body = new ByteBuffer();
      body.writeByte(0x72);
      body.writeULEB128(fields.length);
      for (var i = 0; i < fields.length; i += 1) {
        writeName(body, fields[i].name.name);
        writeValType(body, fieldCodes[i]);
      }
      code = this.#declareType(scope, body);
    } else if (td.tag == TypeDefTag.Variant) {
      let cases = td.cases as GrowableArray<Case>;
      let caseCodes = new GrowableArray<i32>();
      for (let c in cases) {
        let payload = c.type;
        caseCodes.push(
            if (payload == null) 0 else this.#encodeType(scope, payload));
      }
      let body = new ByteBuffer();
      body.writeByte(0x71);
      body.writeULEB128(cases.length);
      for (var i = 0; i < cases.length; i += 1) {
        writeName(body, cases[i].name.name);
        if (cases[i].type == null) {
          body.writeByte(0x00); // no payload
        } else {
          body.writeByte(0x01);
          writeValType(body, caseCodes[i]);
        }
        body.writeByte(0x00); // refines: none (the format still asks)
      }
      code = this.#declareType(scope, body);
    } else if (td.tag == TypeDefTag.Enum) {
      let cases = td.enumCases as GrowableArray<EnumCaseDef>;
      let body = new ByteBuffer();
      body.writeByte(0x6d);
      body.writeULEB128(cases.length);
      for (let c in cases) {
        writeName(body, c.name.name);
      }
      code = this.#declareType(scope, body);
    } else {
      let flags = td.flags as GrowableArray<FlagDef>;
      let body = new ByteBuffer();
      body.writeByte(0x6e);
      body.writeULEB128(flags.length);
      for (let f in flags) {
        writeName(body, f.name.name);
      }
      code = this.#declareType(scope, body);
    }
    return code;
  }

  /**
   * A type expression, as a value-type code. Named constructors were
   * handled by `#encodeTypeDef` — this resolves references to them and
   * builds the anonymous ones, one declaration per distinct shape.
   */
  #encodeType(scope: Scope, t: Type): i32 {
    let prim = primOpcodeOf(t.tag);
    if (prim >= 0) {
      return primCode(prim);
    }
    if (t.tag == TypeTag.Name) {
      let index = this.#namedIndex(scope, (t.name as Id).name);
      if (scope.resourceIndices.has(index)) {
        // A resource name in value position is a handle: `-> bucket`
        // returns `own<bucket>`. The explicit `own`/`borrow` arms below
        // are the ones that look the name up raw.
        return this.#handleType(scope, 0x69, index);
      }
      return index;
    }
    if (t.tag == TypeTag.Future || t.tag == TypeTag.Stream) {
      // `stream<T>`/`future<T>` — a handle to one end. The payload is
      // optional in the grammar (`0x66 t?`), and the absent form is a
      // real type (`future` alone signals completion), encoded as a
      // present/absent byte like a defaulted case payload.
      let opcode = if (t.tag == TypeTag.Stream) 0x66 else 0x65;
      let innerType = t.inner;
      var inner = -1;
      var key = i32ToString(opcode) + "(";
      if (innerType != null) {
        inner = this.#encodeType(scope, innerType);
        key = key + i32ToString(inner);
      }
      key = key + ")";
      if (let (true, existing) = scope.anon.get(key)) {
        return existing;
      }
      let body = new ByteBuffer();
      body.writeByte(opcode);
      if (innerType != null) {
        body.writeByte(0x01);
        writeValType(body, inner);
      } else {
        body.writeByte(0x00);
      }
      let index = this.#declareType(scope, body);
      scope.anon[key] = index;
      return index;
    }
    if (t.tag == TypeTag.Map) {
      throw new EncodeError("map types are not encodable yet");
    }
    if (t.tag == TypeTag.ErrorContext) {
      throw new EncodeError("error-context types are not encodable yet");
    }
    if (t.tag == TypeTag.List && t.fixedLength >= 0) {
      throw new EncodeError("fixed-length lists are not encodable yet");
    }

    if (t.tag == TypeTag.List || t.tag == TypeTag.Option) {
      let inner = this.#encodeType(scope, t.inner as Type);
      let opcode = if (t.tag == TypeTag.List) 0x70 else 0x6b;
      let key = `${i32ToString(opcode)}(${i32ToString(inner)})`;
      if (let (true, existing) = scope.anon.get(key)) {
        return existing;
      }
      let body = new ByteBuffer();
      body.writeByte(opcode);
      writeValType(body, inner);
      let index = this.#declareType(scope, body);
      scope.anon[key] = index;
      return index;
    }
    if (t.tag == TypeTag.Own || t.tag == TypeTag.Borrow) {
      let inner = t.inner as Type;
      if (inner.tag != TypeTag.Name) {
        throw new EncodeError("own/borrow take a resource by name");
      }
      let resource = this.#namedIndex(scope, (inner.name as Id).name);
      let opcode = if (t.tag == TypeTag.Own) 0x69 else 0x68;
      return this.#handleType(scope, opcode, resource);
    }
    if (t.tag == TypeTag.Tuple) {
      let members = t.types as GrowableArray<Type>;
      let codes = new GrowableArray<i32>();
      var key = "tuple(";
      for (let m in members) {
        let c = this.#encodeType(scope, m);
        codes.push(c);
        key = `${key}${i32ToString(c)},`;
      }
      key = key + ")";
      if (let (true, existing) = scope.anon.get(key)) {
        return existing;
      }
      let body = new ByteBuffer();
      body.writeByte(0x6f);
      body.writeULEB128(codes.length);
      for (let c in codes) {
        writeValType(body, c);
      }
      let index = this.#declareType(scope, body);
      scope.anon[key] = index;
      return index;
    }
    if (t.tag == TypeTag.Result) {
      let ok = t.okType;
      let err = t.errType;
      let okCode = if (ok == null) 0 else this.#encodeType(scope, ok);
      let errCode = if (err == null) 0 else this.#encodeType(scope, err);
      let key = "result(" + (if (ok == null) "" else i32ToString(okCode)) +
          "," + (if (err == null) "" else i32ToString(errCode)) + ")";
      if (let (true, existing) = scope.anon.get(key)) {
        return existing;
      }
      let body = new ByteBuffer();
      body.writeByte(0x6a);
      if (ok == null) {
        body.writeByte(0x00);
      } else {
        body.writeByte(0x01);
        writeValType(body, okCode);
      }
      if (err == null) {
        body.writeByte(0x00);
      } else {
        body.writeByte(0x01);
        writeValType(body, errCode);
      }
      let index = this.#declareType(scope, body);
      scope.anon[key] = index;
      return index;
    }
    throw new EncodeError("unhandled type tag in the WIT encoder");
  }

  /**
   * A function type declaration; the index it gets. `selfBorrow` is a
   * borrow handle's index for a method and -1 otherwise.
   */
  #encodeFuncType(
    scope: Scope,
    func: Func,
    selfBorrow: i32,
    isAsync: boolean
  ): i32 {
    let paramCodes = new GrowableArray<i32>();
    for (let p in func.params) {
      paramCodes.push(this.#encodeType(scope, p.type));
    }
    let result = func.result;
    let resultCode =
        if (result == null) 0 else this.#encodeType(scope, result);

    let body = new ByteBuffer();
    body.writeByte(if (isAsync) 0x43 else 0x40);
    body.writeULEB128(
        func.params.length + (if (selfBorrow >= 0) 1 else 0));
    if (selfBorrow >= 0) {
      writeName(body, "self");
      writeValType(body, selfBorrow);
    }
    for (var i = 0; i < func.params.length; i += 1) {
      writeName(body, func.params[i].name.name);
      writeValType(body, paramCodes[i]);
    }
    if (result == null) {
      body.writeByte(0x01); // the named-results arm of resultlist,
      body.writeByte(0x00); // holding none
    } else {
      body.writeByte(0x00); // one unnamed result
      writeValType(body, resultCode);
    }
    return this.#declareType(scope, body);
  }

  #exportFunc(scope: Scope, name: String, typeIndex: i32): void {
    scope.decls.writeByte(0x04);
    writeExternName(scope.decls, name);
    scope.decls.writeByte(0x01); // externdesc: func
    scope.decls.writeULEB128(typeIndex);
    scope.declCount += 1;
  }

  #encodeInterfaceFunc(
    scope: Scope,
    nf: NamedFunc,
    exportPrefix: String,
    selfBorrow: i32
  ): void {
    let typeIndex =
        this.#encodeFuncType(scope, nf.func, selfBorrow, nf.func.isAsync);
    this.#exportFunc(scope, exportPrefix + nf.name.name, typeIndex);
  }

  #encodeResourceFunc(
    scope: Scope,
    rf: ResourceFunc,
    resourceName: String,
    resourceIndex: i32
  ): void {
    if (rf.tag == ResourceFuncTag.Constructor) {
      // A constructor's declared result is nothing; its real one is
      // `own` of the resource it builds.
      let ownIndex = this.#handleType(scope, 0x69, resourceIndex);
      let func = rf.func.func;
      let paramCodes = new GrowableArray<i32>();
      for (let p in func.params) {
        paramCodes.push(this.#encodeType(scope, p.type));
      }
      let body = new ByteBuffer();
      body.writeByte(0x40);
      body.writeULEB128(func.params.length);
      for (var i = 0; i < func.params.length; i += 1) {
        writeName(body, func.params[i].name.name);
        writeValType(body, paramCodes[i]);
      }
      body.writeByte(0x00);
      writeValType(body, ownIndex);
      let typeIndex = this.#declareType(scope, body);
      this.#exportFunc(scope, "[constructor]" + resourceName, typeIndex);
    } else if (rf.tag == ResourceFuncTag.Method) {
      let borrowIndex = this.#handleType(scope, 0x68, resourceIndex);
      this.#encodeInterfaceFunc(scope, rf.func,
          `[method]${resourceName}.`, borrowIndex);
    } else {
      this.#encodeInterfaceFunc(scope, rf.func,
          `[static]${resourceName}.`, -1);
    }
  }

  /** The index `name` exports here, with no handle wrapping. */
  #namedIndex(scope: Scope, name: String): i32 {
    if (let (true, index) = scope.named.get(name)) {
      return index;
    }
    let nestedNamed = scope.nestedNamed;
    if (nestedNamed != null) {
      return nestedNamed(name);
    }
    if (let (true, td) = scope.pending.get(name)) {
      // Declared later in the interface: encode it now, first use
      // being the encoding order.
      this.#encodeTypeDef(scope, td);
      return scope.named[name];
    }
    let source = scope.aliasSource;
    if (source != null) {
      let reg = source;
      if (!this.#declaresType(reg, name)) {
        throw new EncodeError("'" + reg.qualifiedName +
            "' declares no type '" + name + "'");
      }
      // An imported interface's types alias out of its instance. An
      // exported interface has no instance to alias from; a type it
      // `use`s comes from its source instead, under the source's own
      // name for it: an alias out of an imported source's instance, or
      // an exported source's own component-level declaration.
      var index = -1;
      if (this.#instanceIndex.has(reg.qualifiedName)) {
        index = this.#aliasTypeExport(reg.qualifiedName, name);
      } else {
        let hop = this.#useSourceOf(reg, name);
        if (hop == null) {
          // The exported interface's own declaration: encoded at
          // component level, and exported from its instance.
          index = this.#encodeExportedOwnType(reg, name);
        } else {
          index = this.#usedTypeIndex(hop);
        }
      }
      // The alias appended a component-level type; a component-level
      // scope counts the same index space, so it catches up.
      scope.typeCount = this.#result.typeCount;
      scope.named[name] = index;
      if (this.#isResource(reg, name)) {
        scope.resourceIndices[index] = true;
      }
      return index;
    }
    if (scope.atComponentLevel) {
      throw new EncodeError("a world-level function names type '" +
          name + "', which needs world-level `use` encoding");
    }
    throw new EncodeError(`type '${name}' is not declared in this interface`);
  }

  /**
   * The component-level type index of `name`, a type the exported
   * interface `reg` declares itself, encoding it on first use — its
   * body as a component-level type, its named parts resolved against
   * the interface the same way (a record's enum field, a variant's
   * record payload) — and recording it for the instance to export. A
   * resource is a component-level resource type whose representation
   * is an `i32` — the index into the entry wrapper's table of the
   * program's instances — which the canon `resource.new` and
   * `resource.rep` builtins mint handles for and read back. Its
   * destructor is a shim trampoline (`DtorSlot`): the program's own
   * destructor lives in an instance that cannot exist before this type
   * does, since the core module imports `resource.new` for it.
   */
  #encodeExportedOwnType(reg: RegisteredInterface, name: String): i32 {
    let key = `${reg.qualifiedName}#own:${name}`;
    if (let (true, existing) = this.#aliasedTypes.get(key)) {
      return existing;
    }
    var found: TypeDef | null = null;
    for (let item in reg.items) {
      if (item.tag != InterfaceItemTag.TypeDef) { continue; }
      let td = item.typeDef as TypeDef;
      if (td.name.name == name) { found = td; }
    }
    if (found == null) {
      throw new EncodeError(`'${reg.qualifiedName}' declares no type '${name}'`);
    }
    let td = found;
    let scope = new Scope();
    scope.atComponentLevel = true;
    scope.typeCount = this.#result.typeCount;
    scope.aliasSource = reg;
    var index = -1;
    if (td.tag == TypeDefTag.Resource) {
      // The destructor is core function `slot`: the emitter's shim
      // trampoline for this resource (see `DtorSlot`).
      let slot = this.#result.dtorSlots.length;
      this.#result.dtorSlots.push(new DtorSlot(reg.qualifiedName, name));
      let body = new ByteBuffer();
      body.writeByte(0x3f); // resource
      body.writeByte(0x7f); // rep: i32
      body.writeByte(0x01); // a destructor:
      body.writeULEB128(slot);
      index = this.#declareType(scope, body);
    } else if (td.tag == TypeDefTag.Alias) {
      let target = td.aliasType as Type;
      if (target.tag == TypeTag.Name) {
        index = this.#namedIndex(scope, (target.name as Id).name);
      } else {
        let encoded = this.#encodeType(scope, target);
        if (encoded < 0) {
          // A primitive alias still needs a declared type for the
          // instance to export under the name.
          let body = new ByteBuffer();
          body.writeByte(0 - encoded);
          index = this.#declareType(scope, body);
        } else {
          index = encoded;
        }
      }
    } else {
      index = this.#encodeTypeBody(scope, td);
    }
    this.#aliasedTypes[key] = index;
    let list = if (let (true, l) = this.#result.exportedTypes.get(
        reg.qualifiedName)) l else new GrowableArray<ExportedTypeIndex>();
    list.push(new ExportedTypeIndex(name, index));
    this.#result.exportedTypes[reg.qualifiedName] = list;
    return index;
  }

  /** Whether `reg` declares `name` — as a type definition or a `use`d
   * name — so an alias export of it can be valid. */
  #declaresType(reg: RegisteredInterface, name: String): boolean {
    for (let item in reg.items) {
      if (item.tag == InterfaceItemTag.TypeDef) {
        if ((item.typeDef as TypeDef).name.name == name) {
          return true;
        }
      } else if (item.tag == InterfaceItemTag.Use) {
        for (let n in (item.use as Use).names) {
          let asName = n.asName;
          let localName =
              asName?.name ?? n.name.name;
          if (localName == name) {
            return true;
          }
        }
      }
    }
    return false;
  }

  /** An `own`/`borrow` of `resourceIndex`, deduplicated like any anon. */
  #handleType(scope: Scope, opcode: i32, resourceIndex: i32): i32 {
    let key = `${i32ToString(opcode)}(${i32ToString(resourceIndex)})`;
    if (let (true, existing) = scope.anon.get(key)) {
      return existing;
    }
    let body = new ByteBuffer();
    body.writeByte(opcode);
    body.writeULEB128(resourceIndex); // an index position: unsigned
    let index = this.#declareType(scope, body);
    scope.anon[key] = index;
    return index;
  }
}

/** `ns:pkg/name@version`, or the bare name when there is no package. */
export function qualifiedInterfaceName(
  pkg: PackageName | null,
  interfaceName: String
): String {
  if (pkg == null) {
    return interfaceName;
  }
  let p = pkg;
  var name = `${p.namespace.name}:${p.name.name}/${interfaceName}`;
  let version = p.version;
  if (version != null) {
    name = `${name}@${version}`;
  }
  return name;
}

function externName(kind: ExternKind): String {
  if (kind.tag == ExternKindTag.Path) {
    return (kind.path as UsePath).getName().name;
  }
  return (kind.name as Id).name;
}

// ============================================================================
// Canonical flattening metadata
// ============================================================================

/**
 * How a WIT type crosses the core boundary: how many flat core values
 * it occupies, and whether it needs linear memory to cross at all.
 *
 * This is the *counting* half of the canonical ABI's `flatten` — enough
 * to decide two things a `canon lower` depends on: whether the options
 * must name a memory and a realloc (a `string` or `list` anywhere in
 * the signature), and whether the result is returned indirectly
 * (flattened results exceeding one mean the caller passes a return
 * area's address as a trailing `i32` parameter, and so does a
 * parameter list flattening past sixteen).
 */
export final class WitFlatMeta {
  // No field initializers: a defaulted `this.x` parameter on a field
  // that also has an initializer fails ZIR lowering ("auto-box to
  // any") — see elematic/zena#102.
  var flatCount: i32;
  var needsMemory: boolean;
  new(this.flatCount = 0, this.needsMemory = false);
}

/** One function's flattening, plus whether the lookup found it at all. */
export final class WitFuncMeta {
  var paramFlatCount = 0;
  var resultFlatCount = 0;
  /** Whether lowering this function needs the canonical memory options. */
  var needsMemory = false;
  /** Whether the WIT declares the function `async`. */
  var isAsync = false;

}

/** One interface, as the flattening walker sees the document. */
final class FlatIface {
  name: String;
  items: Array<InterfaceItem>;
  new(this.name, this.items);
}

function flatMetaOfType(
  interfaces: Array<FlatIface>,
  owner: FlatIface,
  t: Type
): WitFlatMeta {
  let prim = primOpcodeOf(t.tag);
  if (prim >= 0) {
    if (t.tag == TypeTag.String) {
      return new WitFlatMeta(2, true);
    }
    return new WitFlatMeta(1, false);
  }
  if (t.tag == TypeTag.List) {
    return new WitFlatMeta(2, true);
  }
  if (t.tag == TypeTag.Own || t.tag == TypeTag.Borrow) {
    return new WitFlatMeta(1, false);
  }
  if (t.tag == TypeTag.Tuple) {
    let meta = new WitFlatMeta();
    for (let m in t.types as GrowableArray<Type>) {
      let inner = flatMetaOfType(interfaces, owner, m);
      meta.flatCount += inner.flatCount;
      if (inner.needsMemory) { meta.needsMemory = true; }
    }
    return meta;
  }
  if (t.tag == TypeTag.Option) {
    let inner = flatMetaOfType(interfaces, owner, t.inner as Type);
    return new WitFlatMeta(1 + inner.flatCount, inner.needsMemory);
  }
  if (t.tag == TypeTag.Result) {
    // A variant of two cases: the discriminant, then the larger payload
    // (the join's *count* is the maximum; the exact core types do not
    // matter for what this decides).
    var payload = 0;
    var mem = false;
    let ok = t.okType;
    if (ok != null) {
      let m = flatMetaOfType(interfaces, owner, ok);
      payload = m.flatCount;
      if (m.needsMemory) { mem = true; }
    }
    let err = t.errType;
    if (err != null) {
      let m = flatMetaOfType(interfaces, owner, err);
      if (m.flatCount > payload) { payload = m.flatCount; }
      if (m.needsMemory) { mem = true; }
    }
    return new WitFlatMeta(1 + payload, mem);
  }
  if (t.tag == TypeTag.Name) {
    return flatMetaOfName(interfaces, owner, (t.name as Id).name);
  }
  // stream/future: a handle end, one core i32, no memory of its own —
  // the real answer, not a fallback. map/error-context: the encoder
  // still refuses those before metadata is asked for; one word keeps a
  // caller that asks anyway from being lied to about memory.
  return new WitFlatMeta(1, false);
}

function flatMetaOfName(
  interfaces: Array<FlatIface>,
  owner: FlatIface,
  name: String
): WitFlatMeta {
  for (let item in owner.items) {
    if (item.tag == InterfaceItemTag.TypeDef) {
      let td = item.typeDef as TypeDef;
      if (td.name.name != name) { continue; }
      if (td.tag == TypeDefTag.Resource) {
        // A resource name in value position is a handle.
        return new WitFlatMeta(1, false);
      }
      if (td.tag == TypeDefTag.Enum || td.tag == TypeDefTag.Flags) {
        return new WitFlatMeta(1, false);
      }
      if (td.tag == TypeDefTag.Record) {
        let meta = new WitFlatMeta();
        for (let f in td.fields as GrowableArray<Field>) {
          let inner = flatMetaOfType(interfaces, owner, f.type);
          meta.flatCount += inner.flatCount;
          if (inner.needsMemory) { meta.needsMemory = true; }
        }
        return meta;
      }
      if (td.tag == TypeDefTag.Variant) {
        var payload = 0;
        var mem = false;
        for (let c in td.cases as GrowableArray<Case>) {
          let payloadType = c.type;
          if (payloadType != null) {
            let m = flatMetaOfType(interfaces, owner, payloadType);
            if (m.flatCount > payload) { payload = m.flatCount; }
            if (m.needsMemory) { mem = true; }
          }
        }
        return new WitFlatMeta(1 + payload, mem);
      }
      return flatMetaOfType(interfaces, owner, td.aliasType as Type);
    } else if (item.tag == InterfaceItemTag.Use) {
      let use = item.use as Use;
      for (let n in use.names) {
        let asName = n.asName;
        let localName =
            asName?.name ?? n.name.name;
        if (localName != name) { continue; }
        // The wanted interface, package-qualified. A bare `use foo`
        // means the OWNER's package's `foo` — matching by trailing
        // name alone resolved wasi:http/client's `use types` to
        // wasi:cli/types, whichever registered first — and a
        // package-path use spells its package outright.
        let sourceName = use.from.getName().name;
        let from = use.from;
        var wantPackage = "";
        if (from is PackageUsePath) {
          let p = from.packageId as PackageName;
          wantPackage = `${p.namespace.name}:${p.name.name}`;
        } else {
          var slashAt = -1;
          for (var i = 0; i < owner.name.length; i += 1) {
            if (owner.name.getByteAt(i) == 47) { slashAt = i; } // '/'
          }
          if (slashAt > 0) {
            wantPackage = owner.name.sliceBytes(0, slashAt);
          }
        }
        let want = `${wantPackage}/${sourceName}`;
        for (let iface in interfaces) {
          if (iface.name == want || iface.name.startsWith(want + "@")) {
            return flatMetaOfName(interfaces, iface, n.name.name);
          }
        }
      }
    }
  }
  var known = "";
  for (let iface in interfaces) {
    known = `${known} ${iface.name}`;
  }
  throw new EncodeError("flattening cannot resolve type '" + name +
      "' (interfaces:" + known + ")");
}

function funcMetaOf(
  interfaces: Array<FlatIface>,
  owner: FlatIface,
  func: Func,
  selfParams: i32
) {
  let meta = new WitFuncMeta();
  meta.isAsync = func.isAsync;
  meta.paramFlatCount = selfParams;
  for (let p in func.params) {
    let m = flatMetaOfType(interfaces, owner, p.type);
    meta.paramFlatCount += m.flatCount;
    if (m.needsMemory) { meta.needsMemory = true; }
  }
  let result = func.result;
  if (result != null) {
    let m = flatMetaOfType(interfaces, owner, result);
    meta.resultFlatCount = m.flatCount;
    if (m.needsMemory) { meta.needsMemory = true; }
  }
  if (meta.paramFlatCount > 16 || meta.resultFlatCount > 1) {
    // Spilled parameters land in memory; an indirect result needs a
    // return area. Either way the options must say where.
    meta.needsMemory = true;
  }
  if (meta.isAsync &&
      (meta.resultFlatCount > 0 || meta.paramFlatCount > 4)) {
    // The async lowering spills any result through a return area, and
    // parameters past four core values through one pointer.
    meta.needsMemory = true;
  }
  return meta;
}

/**
 * The flattening of one function of one interface, by the names a core
 * module imports them under — the qualified interface, and the field
 * (`get-stdout`, `[method]output-stream.blocking-write-and-flush`).
 * Null when the interface or the function is not in the document,
 * which callers treat as its own loud error.
 */
/** Every interface of the document, main package and nested. */
function registeredFlatIfaces(ast: Ast) {
  let interfaces = new GrowableArray<FlatIface>();
  let register = (pkg: PackageName | null, items: Array<AstItem>) => {
    for (let item in items) {
      if (item.tag == AstItemTag.Interface) {
        let def = item.interfaceDef as InterfaceDef;
        interfaces.push(new FlatIface(
            qualifiedInterfaceName(pkg, def.name.name), def.items));
      }
    }
  };
  register(ast.packageName, ast.items);
  for (let nested in ast.nestedPackages) {
    register(nested.name, nested.items);
  }
  return interfaces;
}

/**
 * An export's flattening: the lift moves parameters and result
 * through memory when a type of theirs does, or when either spills
 * past sixteen core values. An async import's result spills through a
 * return area; an async export's goes through `task.return`, whose
 * flat parameters carry it, so the import rule does not apply.
 */
function exportMetaOf(
  interfaces: Array<FlatIface>,
  owner: FlatIface,
  func: Func,
  selfParams: i32 = 0
) {
  let meta = new WitFuncMeta();
  meta.isAsync = func.isAsync;
  meta.paramFlatCount = selfParams;
  for (let p in func.params) {
    let m = flatMetaOfType(interfaces, owner, p.type);
    meta.paramFlatCount += m.flatCount;
    if (m.needsMemory) { meta.needsMemory = true; }
  }
  let result = func.result;
  if (result != null) {
    let m = flatMetaOfType(interfaces, owner, result);
    meta.resultFlatCount = m.flatCount;
    if (m.needsMemory) { meta.needsMemory = true; }
  }
  if (meta.paramFlatCount > 16 || meta.resultFlatCount > 16) {
    meta.needsMemory = true;
  }
  return meta;
}

/**
 * The flattening of the world's function export `exportName`, or null
 * when the world exports no function by that name. A world-level
 * function's types are structural, so they resolve against no
 * interface.
 *
 * The memory need is an export's, not an import's: the lift moves
 * parameters and result through memory when a type of theirs does, or
 * when either spills past sixteen core values. An async import's
 * result spills through a return area; an async export's goes through
 * `task.return`, whose flat parameters carry it.
 */
export function worldFuncFlatMeta(
  ast: Ast,
  worldName: String,
  exportName: String
): WitFuncMeta | null {
  let interfaces = new GrowableArray<FlatIface>();
  for (let item in ast.items) {
    if (item.tag == AstItemTag.Interface) {
      let def = item.interfaceDef as InterfaceDef;
      interfaces.push(new FlatIface(
          qualifiedInterfaceName(ast.packageName, def.name.name),
          def.items));
    }
  }
  let owner = new FlatIface("", new GrowableArray<InterfaceItem>());
  for (let item in ast.items) {
    if (item.tag != AstItemTag.World) { continue; }
    let def = item.worldDef as WorldDef;
    if (def.name.name != worldName) { continue; }
    for (let wi in expandedWorldItems(ast, def)) {
      if (wi.tag != WorldItemTag.Export) { continue; }
      let kind = (wi.exportItem as Export).kind;
      if (kind.tag != ExternKindTag.Func) { continue; }
      if ((kind.name as Id).name != exportName) { continue; }
      return exportMetaOf(interfaces, owner, kind.funcDef as Func);
    }
  }
  return null;
}

/**
 * The flattening of `funcName` in the exported interface
 * `interfaceName`, or null when no such function exists. The memory
 * need is an export's, as `worldFuncFlatMeta` computes it.
 */
export function interfaceExportFlatMeta(
  ast: Ast,
  interfaceName: String,
  funcName: String
): WitFuncMeta | null {
  let interfaces = registeredFlatIfaces(ast);
  for (let iface in interfaces) {
    if (iface.name != interfaceName) { continue; }
    for (let item in iface.items) {
      if (item.tag != InterfaceItemTag.Func) { continue; }
      let nf = item.func as NamedFunc;
      if (nf.name.name == funcName) {
        return exportMetaOf(interfaces, iface, nf.func);
      }
    }
    // A resource's function under its mangled export name: a method's
    // `self` is one core value, and a constructor returns the handle.
    let found = resourceFuncNamed(iface.items, funcName);
    if (found != null) {
      let rf = found.rf;
      let selfParams = if (rf.tag == ResourceFuncTag.Method) 1 else 0;
      let meta = exportMetaOf(interfaces, iface, rf.func.func, selfParams);
      if (rf.tag == ResourceFuncTag.Constructor) {
        meta.resultFlatCount = 1; // the own handle
      }
      return meta;
    }
  }
  return null;
}

/** A resource's function found by its mangled export name. */
final class NamedResourceFunc {
  resourceName: String;
  rf: ResourceFunc;
  new(this.resourceName, this.rf);
}

/**
 * The resource function `items` exports as `fieldName` — a
 * `[constructor]r`, `[method]r.f` or `[static]r.f` — or null.
 */
function resourceFuncNamed(items: Array<InterfaceItem>,
    fieldName: String): NamedResourceFunc | null {
  for (let item in items) {
    if (item.tag != InterfaceItemTag.TypeDef) { continue; }
    let td = item.typeDef as TypeDef;
    if (td.tag != TypeDefTag.Resource) { continue; }
    let resourceName = td.name.name;
    for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
      let exported = if (rf.tag == ResourceFuncTag.Constructor) {
        "[constructor]" + resourceName
      } else if (rf.tag == ResourceFuncTag.Method) {
        `[method]${resourceName}.${rf.func.name.name}`
      } else {
        `[static]${resourceName}.${rf.func.name.name}`
      };
      if (exported == fieldName) {
        return new NamedResourceFunc(resourceName, rf);
      }
    }
  }
  return null;
}


export function funcFlatMeta(
  ast: Ast,
  interfaceName: String,
  fieldName: String
): WitFuncMeta | null {
  let interfaces = new GrowableArray<FlatIface>();
  let register = (pkg: PackageName | null, items: Array<AstItem>) => {
    for (let item in items) {
      if (item.tag == AstItemTag.Interface) {
        let def = item.interfaceDef as InterfaceDef;
        interfaces.push(new FlatIface(
            qualifiedInterfaceName(pkg, def.name.name), def.items));
      }
    }
  };
  register(ast.packageName, ast.items);
  for (let nested in ast.nestedPackages) {
    register(nested.name, nested.items);
  }

  for (let iface in interfaces) {
    if (iface.name != interfaceName) { continue; }
    for (let item in iface.items) {
      if (item.tag == InterfaceItemTag.Func) {
        let nf = item.func as NamedFunc;
        if (nf.name.name == fieldName) {
          return funcMetaOf(interfaces, iface, nf.func, 0);
        }
      } else if (item.tag == InterfaceItemTag.TypeDef) {
        let td = item.typeDef as TypeDef;
        if (td.tag != TypeDefTag.Resource) { continue; }
        let resourceName = td.name.name;
        for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
          var exported = "";
          var selfParams = 0;
          if (rf.tag == ResourceFuncTag.Constructor) {
            exported = "[constructor]" + resourceName;
          } else if (rf.tag == ResourceFuncTag.Method) {
            exported = `[method]${resourceName}.${rf.func.name.name}`;
            selfParams = 1;
          } else {
            exported = `[static]${resourceName}.${rf.func.name.name}`;
          }
          if (exported != fieldName) { continue; }
          let meta =
              funcMetaOf(interfaces, iface, rf.func.func, selfParams);
          if (rf.tag == ResourceFuncTag.Constructor) {
            meta.resultFlatCount = 1; // the own handle
          }
          return meta;
        }
      }
    }
    return null;
  }
  return null;
}

/**
 * The items of `world`, a world of the document's main package, with
 * every `include` expanded in place: the included world's imports and
 * exports, its own includes expanded too, in order. An include names a
 * world of the including world's package by a bare name, or of another
 * package by path. An item that an included world names an interface by
 * a bare name means that world's package's interface, so its path comes
 * back qualified with the package. An import or export that two
 * includes both bring is kept once, as WIT merges them. An item gated
 * `@unstable(feature = ...)` is left out, as WIT tooling leaves it out
 * while no feature is enabled: `wasi:clocks/imports` gates `timezone`,
 * which hosts do not provide.
 */
export function expandedWorldItems(ast: Ast, world: WorldDef): GrowableArray<WorldItem> {
  let out = new GrowableArray<WorldItem>();
  appendWorldItems(ast, world, ast.packageName, false, out,
      new GrowableArray<String>(), 0);
  return out;
}

function appendWorldItems(ast: Ast, world: WorldDef, pkg: PackageName | null,
    included: boolean, out: GrowableArray<WorldItem>, seen: GrowableArray<String>,
    depth: i32): void {
  if (depth > 32) {
    throw new EncodeError(`world '${world.name.name}' includes itself`);
  }
  for (let item in world.items) {
    if (item.tag == WorldItemTag.Include) {
      let inc = item.include as Include;
      if (isUnstable(inc.docs)) { continue; }
      if (inc.names.length > 0) {
        throw new EncodeError("an `include` that renames with `with` is not encodable yet");
      }
      let from = inc.from;
      if (from.tag == UsePathTag.Id) {
        let name = (from.id as Id).name;
        appendWorldItems(ast, findPackageWorld(ast, pkg, name), pkg, true, out, seen,
            depth + 1);
      } else {
        let fromPkg = from.packageId as PackageName;
        appendWorldItems(ast, findPackageWorld(ast, fromPkg, (from.name as Id).name),
            fromPkg, true, out, seen, depth + 1);
      }
      continue;
    }
    if (item.tag != WorldItemTag.Import && item.tag != WorldItemTag.Export) {
      out.push(item);
      continue;
    }
    let isImport = item.tag == WorldItemTag.Import;
    let docs = if (isImport) (item.importItem as Import).docs
        else (item.exportItem as Export).docs;
    if (isUnstable(docs)) { continue; }
    let kind = if (isImport) (item.importItem as Import).kind
        else (item.exportItem as Export).kind;
    let key = `${if (isImport) 'import' else 'export'} ${externKey(kind, pkg)}`;
    var known = false;
    for (let k in seen) {
      if (k == key) { known = true; }
    }
    if (known) { continue; }
    seen.push(key);
    let path = kind.path;
    if (!included || kind.tag != ExternKindTag.Path || path == null ||
        path.tag != UsePathTag.Id || pkg == null) {
      out.push(item);
      continue;
    }
    let qualified = ExternKind.fromPath(UsePath.fromPackage(pkg, path.id as Id));
    out.push(if (isImport) {
      WorldItem.fromImport(new Import((item.importItem as Import).docs, qualified))
    } else {
      WorldItem.fromExport(new Export((item.exportItem as Export).docs, qualified))
    });
  }
}

/** Whether an item is gated behind a feature with `@unstable`. */
function isUnstable(docs: Docs): boolean {
  let attributes = docs.attributes;
  if (attributes == null) {
    return false;
  }
  for (let attribute in attributes) {
    if (attribute.tag == AttributeTag.Unstable) {
      return true;
    }
  }
  return false;
}

/** What identifies an import or export: its qualified interface, or its name. */
function externKey(kind: ExternKind, pkg: PackageName | null): String {
  let path = kind.path;
  if (kind.tag == ExternKindTag.Path && path != null) {
    return if (path.tag == UsePathTag.Id) {
      qualifiedInterfaceName(pkg, (path.id as Id).name)
    } else {
      qualifiedInterfaceName(path.packageId, (path.name as Id).name)
    };
  }
  return (kind.name as Id).name;
}

/** The world named `name` in package `pkg`: the main one, or a nested one. */
function findPackageWorld(ast: Ast, pkg: PackageName | null, name: String): WorldDef {
  let wanted = qualifiedInterfaceName(pkg, name);
  if (qualifiedInterfaceName(ast.packageName, name) == wanted) {
    for (let item in ast.items) {
      if (item.tag == AstItemTag.World && (item.worldDef as WorldDef).name.name == name) {
        return item.worldDef as WorldDef;
      }
    }
  }
  for (let nested in ast.nestedPackages) {
    if (qualifiedInterfaceName(nested.name, name) != wanted) { continue; }
    for (let item in nested.items) {
      if (item.tag == AstItemTag.World && (item.worldDef as WorldDef).name.name == name) {
        return item.worldDef as WorldDef;
      }
    }
  }
  throw new EncodeError(`no world '${wanted}' to include in this document`);
}

/** The names of the worlds the document's main package defines. */
export function worldNames(ast: Ast): Array<String> {
  let names = new GrowableArray<String>();
  for (let item in ast.items) {
    if (item.tag == AstItemTag.World) {
      names.push((item.worldDef as WorldDef).name.name);
    }
  }
  return names;
}

/** A world's encoding, plus the bytes as a complete component. */
export final class TypesOnlyComponent {
  bytes: ByteBuffer;
  encoded: EncodedWorld;
  new(this.bytes, this.encoded);
}

/**
 * The pieces as a complete, importing-only component: the head sections
 * with nothing behind them. Valid on its own — which is the point, as
 * `wasm-tools component wit` will read the world back out of it.
 */
export function encodeTypesOnlyComponent(
  ast: Ast,
  worldName: String
): TypesOnlyComponent {
  let encoder = new ComponentTypeEncoder(ast);
  let encoded = encoder.encodeWorld(worldName);
  let out = new ByteBuffer();
  out.writeU32(0x6D736100); // \0asm
  out.writeU32(0x0001000D); // version 0x0d, layer 1: a component
  for (let piece in encoded.pieces) {
    out.writeByte(piece.id);
    out.writeULEB128(piece.payload.length);
    out.writeBuffer(piece.payload);
  }
  return new TypesOnlyComponent(out, encoded);
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none