@swf2es/codegen 0.0.0-stage → 0.1.1

package/src/index.ts

@@ -0,0 +1,738 @@
+/**
+ * Compiles ABC and AVM1 bytecode to ES modules.
+ *
+ * The compiler itself is AssemblyScript (assembly/), built to codegen.wasm.
+ * This wrapper instantiates it and gives its exports their types. The same wasm runs as the browser JIT
+ * (a module per ABC as its SWF loads) and as the ahead-of-time compiler,
+ * so both produce identical output. See docs/architecture/overview.md.
+ */
+import { AIR_API_VERSION, API_VERSION, checkApiVersion } from "@swf2es/format";
+import { instantiate } from "./codegen.js";
+
+/** Bumped whenever generated code or the runtime ABI it calls changes. */
+export const COMPILER_VERSION = "0.0.0";
+
+// The API versions the player and the swf2es command reset the compiler
+// with, which module cache keys name: Flash Player's, and AIR's, whose
+// series has the names Flash Player's leaves out. format's, which the
+// runtime takes too.
+export { AIR_API_VERSION, API_VERSION };
+
+/** The ABCs added to a compiler, by their indices: each one's hash, and whether it was added as a library. */
+export interface AddedAbcs {
+  readonly hashes: readonly string[];
+  readonly builtins: readonly boolean[];
+}
+
+/**
+ * The log's entries made while only the first `count` ABCs, the libraries,
+ * were added, as a key names them: by the SHA-256 of libraryLog's text,
+ * taken once, since they are the same in every later module's context.
+ */
+export interface LibraryDigest {
+  count: number;
+  digest: string;
+}
+
+/** The text whose SHA-256 is a LibraryDigest's, for ABC `index`, any added after the first `count`. */
+export function libraryLog(codegen: Codegen, index: number, count: number): string {
+  return codegen.context(index, 0, count)?.log ?? "";
+}
+
+/**
+ * The text of ABC `index`'s module cache key, whose UTF-8's SHA-256 is the
+ * key: what the module depends on, the compiler's identity, the API
+ * version, every ABC its domain sees, by hash and whether it is a library,
+ * those added after it included, its own place among them, and the
+ * compiler's log about them (see Codegen.context), the libraries' part by
+ * its digest once taken. The player's module cache and the swf2es command
+ * both key by it, so that the command's modules are the cache's. Null
+ * where there is no context.
+ */
+export function moduleKey(
+  codegen: Codegen,
+  index: number,
+  abcs: AddedAbcs,
+  libraries: LibraryDigest | null,
+): string | null {
+  const context = codegen.context(index, libraries?.count ?? 0);
+  if (!context) {
+    return null;
+  }
+
+  return JSON.stringify({
+    compiler: codegen.identity,
+    api: codegen.apiVersion,
+    abcs: context.abcs.map((i) => `${abcs.builtins[i] ? "builtin " : ""}${abcs.hashes[i]}`),
+    own: context.own,
+    libraries,
+    log: context.log,
+  });
+}
+
+/**
+ * A SWF's AVM1 action blocks, as format's readActions lists them: the SWF's
+ * version and each block's range in its decompressed bytes.
+ */
+export interface ActionBlocks {
+  readonly version: number;
+  readonly blocks: readonly { readonly offset: number; readonly length: number }[];
+}
+
+/** What a SWF's action blocks compile to: one module, and each block's entry in it. */
+export interface CompiledActions {
+  module: string;
+  /** By block index: the block's entry in the module, as it compiles alone. */
+  entries: string[];
+  /** By key, each unit in the module's units, as it compiles alone. */
+  units: Map<string, ModuleUnit>;
+}
+
+/**
+ * Where control goes on in a unit, as V.far is called: an offset in the
+ * SWF's decompressed bytes, where the region it goes on in ends, where its
+ * actions' bytes end, and whether it runs as a SWF 5's function. The
+ * module's units are keyed by these, joined with commas.
+ */
+export interface ActionUnit {
+  readonly at: number;
+  readonly end: number;
+  readonly bound: number;
+  readonly five: boolean;
+}
+
+/**
+ * A unit's code, and what it depends on: it runs as well for any region
+ * that ends at or past `high` whose actions' bytes end at or past `reach`,
+ * -1 for only the one it was compiled for.
+ */
+export interface CompiledUnit {
+  code: string;
+  high: number;
+  reach: number;
+}
+
+/** A unit of a module's units, and what it was compiled for. */
+export interface ModuleUnit extends CompiledUnit {
+  unit: ActionUnit;
+}
+
+/**
+ * The text of the module cache key of a SWF's AVM1 module, whose UTF-8's
+ * SHA-256 is the key: the compiler's identity, the SWF's version, which
+ * picks the operations its code calls, and `hash`, the SHA-256 of the
+ * SWF's decompressed bytes, which hold its blocks. An AVM1 module links to
+ * nothing, so nothing else goes in.
+ */
+export function actionsKey(codegen: Codegen, hash: string, version: number): string {
+  return JSON.stringify({ compiler: codegen.identity, avm1: version, swf: hash });
+}
+
+/**
+ * A definition an application domain has found by name, or as a type,
+ * which is not the first one from the root down, as the runtime reports it:
+ * what the domain's later ABCs compile against (see Codegen.found).
+ */
+export interface FoundDefinition {
+  /** The application domain that found it. */
+  domain: number;
+  /** The name's namespace: its kind (0 public, 1 package-internal, ...) and URI. */
+  nsKind: number;
+  uri: string;
+  name: string;
+  /** The ABC that defines it, by its position among those added. */
+  abc: number;
+  /** Found as a type (avmplus' cached traits), else by name (cached scripts). */
+  asType: boolean;
+}
+
+export interface AbcVersion {
+  major: number;
+  minor: number;
+}
+
+/** What an ABC compiles to: its module, the module's source map, and each compiled method body's entry in it. */
+export interface Compiled {
+  module: string;
+  /** JSON: the module's lines mapped to the AS3 lines debugline names. */
+  sourceMap: string;
+  /** By method body index: the body's entry in the module's F, as the JIT compiles it alone. */
+  entries: Map<number, string>;
+}
+
+/**
+ * What ABC `index`'s module depends on in the domain beyond the ABCs'
+ * bytes (see Codegen.context).
+ */
+export interface ModuleContext {
+  /** The ABCs its application domain sees, by their positions among those added, in load order. */
+  abcs: number[];
+  /** Its own place in `abcs`. */
+  own: number;
+  /**
+   * The domain's log about those ABCs, in order: the lazy answers fixed so
+   * far and the findings recorded, each with how many of `abcs` there were.
+   */
+  log: string;
+}
+
+/** A module compiled, and what compiling it fixed in the domain, to replay in its place (Codegen.replay); null where it cannot be. */
+export interface LoggedModule {
+  module: string;
+  log: string | null;
+}
+
+/**
+ * The compiler. ABCs are added to a domain in the order the SWF loads them
+ * (the builtins first), and the last one added compiles, whole or a method
+ * at a time, to code that is byte for byte the same either way.
+ */
+export interface Codegen {
+  /**
+   * The identity of this codegen.wasm, a hash of its bytes that its build
+   * stamps it with; null for one built without it.
+   */
+  readonly identity: string | null;
+  /** The version at the start of an ABC block, or null if it is too short. */
+  abcVersion(abc: Uint8Array): AbcVersion | null;
+  /**
+   * Start a domain whose user ABCs have API version `apiVersion`: Flash
+   * Player's, API_VERSION, by default, or AIR's, AIR_API_VERSION; one
+   * that is neither series' (checkApiVersion) is a RangeError.
+   */
+  reset(apiVersion?: number): void;
+  /** The API version of the last reset. */
+  readonly apiVersion: number;
+  /**
+   * Add an ABC, loaded into application domain `appDomain` (0, the root, by
+   * default), linking it against what that domain sees of those before it;
+   * 0, or the VerifyError it was rejected with (then it is not added).
+   * Throws for an application domain never made, or dropped.
+   */
+  add(abc: Uint8Array, builtin?: boolean, appDomain?: number): number;
+  /** A new application domain, a child of `parent`: its number. Throws for a `parent` never made, or dropped. */
+  childDomain(parent: number): number;
+  /**
+   * Drop application domain `appDomain` and its descendants once nothing
+   * can run their code: no other sees their ABCs, which compile no more,
+   * and compact reuses the memory they took. The indices of the ABCs added
+   * after them do not change, and neither does what those compile to.
+   * Nothing, if `epoch` is given and the domain was reset since.
+   */
+  dropDomain(appDomain: number, epoch?: number): void;
+  /**
+   * How many times `reset` has started a domain: a host that keeps the
+   * number a domain had passes it to dropDomain, which then drops nothing
+   * if the domain was reset since, as when another player took the Codegen
+   * over and its numbers are another domain's.
+   */
+  readonly epoch: number;
+  /**
+   * Rebuild the domain without the ABCs of dropped and evicted domains, if
+   * memory would otherwise grow and they hold enough to keep it from
+   * growing: whether it did. A rebuild links every live ABC again, tens of
+   * milliseconds for a large application, so a host calls this when it has
+   * time, as when idle; nothing else does.
+   */
+  compact(): boolean;
+  /**
+   * What the ABCs hold of codegen's memory, roughly, in bytes: the live
+   * ones', and the dropped and evicted domains' that compact would free;
+   * and the size of codegen's memory, which never shrinks.
+   */
+  usage(): { live: number; dead: number; memory: number };
+  /**
+   * Evict application domain `appDomain` and its descendants while the host
+   * has no use for them, as once their ABCs are compiled: as dropped, but
+   * reviveDomain makes one live again. compact reuses what they took
+   * meanwhile, all but their findings, what was first resolved of them,
+   * and their ABCs' places.
+   */
+  evictDomain(appDomain: number): void;
+  /** Whether application domain `appDomain` is live: made, and neither evicted nor dropped. */
+  isLive(appDomain: number): boolean;
+  /**
+   * Make evicted application domain `appDomain` live again, with its evicted
+   * ancestors, the first of them a child of a live domain: given all their
+   * ABCs again by their indices, as they were added, their ABCs link as
+   * they did, by one rebuild at most, and what they found holds. Throws if
+   * they cannot be.
+   */
+  reviveDomain(appDomain: number, abcs: Map<number, Uint8Array>): void;
+  /** Record a definition an application domain has found; it holds for the ABCs added after. */
+  found(definition: FoundDefinition): void;
+  /**
+   * ABC `index` compiled whole, the last added by default, against every ABC
+   * added so far, later ones included, so a SWF's DoABCs may all be added
+   * before any compiles; `hashes` are the ABCs' hashes in load order, as
+   * the cache key names them.
+   */
+  compile(hashes?: string[], index?: number): Compiled;
+  /**
+   * ABC `index`'s module alone, as `compile` writes it, for a host that
+   * loads it and needs neither its source map nor its entries: writing
+   * those too would add a large ABC's worth to codegen's memory, which
+   * never shrinks.
+   */
+  compileModule(hashes?: string[], index?: number): string;
+  /**
+   * An opt-in JIT module's tables and lazy factories. Its default export
+   * takes (rt, jit); jit(body, bindings) returns that body's factory.
+   * Verification still runs now to fix scopes against the current domain.
+   * This module is not an AOT module and must not enter the module cache.
+   */
+  compileLazyModule(hashes?: string[], index?: number): string;
+  /**
+   * Method bodies of ABC `index` (the last added by default) compiled
+   * alone, as the optional lazy JIT compiles each on first factory use;
+   * a native, unverified or unknown one is left out. Each is byte for byte
+   * its entry in the whole module.
+   */
+  compileMethods(bodies: number[], index?: number): Map<number, string>;
+  /**
+   * What ABC `index`'s module depends on beyond the ABCs' bytes, for a
+   * cache key: besides the ABCs its domain sees, what the domain has
+   * fixed of what resolves lazily, which a later ABC in an ancestor would
+   * change were it first asked now. Its log only of the entries made with
+   * more than `after` ABCs added, and `upTo` at most unless negative. Null
+   * for an ABC never added.
+   */
+  context(index?: number, after?: number, upTo?: number): ModuleContext | null;
+  /**
+   * A string that changes whenever a context might: a host that took one
+   * and finds this the same since need not take it again.
+   */
+  revision(): string;
+  /** compileModule, with what the compile fixed in the domain (see replay). */
+  compileModuleLogged(hashes?: string[], index?: number): LoggedModule;
+  /**
+   * Fix in the domain what compiling ABC `index` did, from the log
+   * compileModuleLogged gave with its module, in place of compiling it:
+   * the domain is then as the compile would have left it, if its context
+   * is the one that compile had. False if the log is malformed or an
+   * entry fails, after doing those before it.
+   */
+  replay(log: string, index?: number): boolean;
+  /**
+   * A SWF's AVM1 action blocks compiled to one module, `bytes` the SWF's
+   * decompressed bytes, which the blocks' ranges are of (format's
+   * `Swf.bytes`), with each block's entry in it. Needs no domain: AVM1 code
+   * links to nothing.
+   */
+  compileActions(bytes: Uint8Array, actions: ActionBlocks): CompiledActions;
+  /** compileActions' module alone. */
+  compileActionsModule(bytes: Uint8Array, actions: ActionBlocks): string;
+  /**
+   * Blocks of a SWF compiled alone, by index, as a JIT may compile each
+   * when it first runs: each byte for byte its entry in the SWF's module.
+   * An index with no block is left out.
+   */
+  compileActionBlocks(
+    bytes: Uint8Array,
+    actions: ActionBlocks,
+    blocks: number[],
+  ): Map<number, string>;
+  /**
+   * A unit of a SWF compiled alone, as V.far asks for it when control first
+   * goes on there: byte for byte its entry in the module's units.
+   */
+  compileActionUnit(bytes: Uint8Array, actions: ActionBlocks, unit: ActionUnit): CompiledUnit;
+  /**
+   * Let go of the copy of a SWF compileActionBlocks and compileActionUnit
+   * keep, as the host lets the SWF go; it is let go too once `bytes` are
+   * collected, and when blocks or units of other SWFs are asked for since.
+   */
+  releaseActions(bytes: Uint8Array): void;
+  /** How many SWFs compileActionBlocks and compileActionUnit keep a copy of, and how many times they have copied one in. */
+  heldActions(): { held: number; copies: number };
+}
+
+/**
+ * Instantiate the compiler from a compiled codegen.wasm module. Loading the
+ * bytes is left to the caller (fetch in browsers, fs in node), which keeps
+ * this package free of I/O. The file ships as `@swf2es/codegen/codegen.wasm`.
+ */
+export async function createCodegen(module: WebAssembly.Module): Promise<Codegen> {
+  const wasm = await instantiate(module, { env: {} });
+  const version = wasm.compilerVersion();
+  if (version !== COMPILER_VERSION) {
+    throw new Error(
+      `codegen.wasm is version ${version} but the wrapper expects ${COMPILER_VERSION}`,
+    );
+  }
+
+  // Of the same version, but built before its modules were handed out in
+  // place: its *Bytes exports return copies, which this wrapper cannot read.
+  // Asked of the module, as the bindings define every export they know of.
+  if (!WebAssembly.Module.exports(module).some((e) => e.name === "outputLength")) {
+    throw new Error(
+      "codegen.wasm has no outputLength export, which the wrapper expects: it is older than the wrapper",
+    );
+  }
+
+  // codegen.wasm uses AssemblyScript's minimal runtime, which collects
+  // garbage only when asked. Nothing runs in wasm between calls, so that is
+  // when: every COLLECT_EVERY calls, and after a call that grew memory.
+  // Memory never shrinks, so collecting only on growth would let each
+  // cycle's garbage grow it a little further.
+  let size = wasm.memory.buffer.byteLength;
+  let calls = 0;
+  let methodBytes = 0;
+  // Whether the domain has an ABC to compile: asking before is a mistake worth a message, not a trap.
+  let added = 0;
+  const last = (what: string) => {
+    if (added === 0) {
+      throw new Error(`${what}: no ABC has been added to the domain`);
+    }
+  };
+  // An ABC by its position among those added, -1 for the last.
+  const indexOf = (index: number) => {
+    if (index >= 0 && (!Number.isInteger(index) || index >= added)) {
+      throw new Error(`ABC ${index}: only ${added} have been added to the domain`);
+    }
+
+    return index < 0 ? -1 : index;
+  };
+  // ABC `index`'s module, its source map and entries kept for `keep`. A
+  // module is never empty: the ABC was of a dropped application domain.
+  const moduleOf = (hashes: string[], index: number, keep: boolean, lazy = false) => {
+    // Only the hashes the module names: joining every ABC's for each
+    // compile took megabytes of codegen's memory a few thousand loads on.
+    const at = indexOf(index);
+    const own = at < 0 ? added - 1 : at;
+    const linked = collected(wasm.domainLinked(at));
+    const named = [hashes[own] ?? ""];
+    for (const i of linked ? linked.split(",") : []) {
+      named.push(hashes[Number(i)] ?? "");
+    }
+
+    // Its bytes decoded here: lifted as a string, a module of megabytes took
+    // longer than compiling it. The emitter writes only well-formed UTF-8,
+    // which decodes alike either way.
+    const address = lazy
+      ? wasm.domainLazyModuleBytes(named.join("\n"), at)
+      : wasm.domainModuleBytes(named.join("\n"), at, keep, true);
+    const module = collected(handed(address, wasm.outputLength()), lazy);
+    if (module === "") {
+      throw new Error(`ABC ${index}: its application domain was dropped`);
+    }
+
+    return module;
+  };
+  const ranges = (actions: ActionBlocks) =>
+    [
+      Int32Array.from(actions.blocks, (b) => b.offset),
+      Int32Array.from(actions.blocks, (b) => b.length),
+    ] as const;
+  // The SWFs whose blocks or units compileActionBlocks and compileActionUnit
+  // compile, which wasm holds by a handle each: the few used last, so that
+  // blocks and units of SWFs that alternate do not copy them in again, each
+  // let go as its bytes are collected.
+  const holding = new WeakMap<Uint8Array, { handle: number; actions: ActionBlocks }>();
+  const holds: number[] = [];
+  let handles = 0;
+  let copies = 0;
+  const release = (handle: number) => {
+    const at = holds.indexOf(handle);
+    if (at >= 0) {
+      holds.splice(at, 1);
+      wasm.actionsRelease(handle);
+    }
+  };
+  const collectedSwfs = new FinalizationRegistry<number>(release);
+  const hold = (bytes: Uint8Array, actions: ActionBlocks): number => {
+    const known = holding.get(bytes);
+    if (known !== undefined && known.actions === actions && holds.includes(known.handle)) {
+      holds.splice(holds.indexOf(known.handle), 1);
+      holds.push(known.handle);
+      return known.handle;
+    }
+
+    if (known !== undefined) {
+      release(known.handle);
+      collectedSwfs.unregister(known);
+    }
+
+    const handle = ++handles;
+    const [offsets, lengths] = ranges(actions);
+    wasm.actionsHold(handle, bytes, offsets, lengths);
+    copies++;
+    const record = { handle, actions };
+    holding.set(bytes, record);
+    collectedSwfs.register(bytes, handle, record);
+    holds.push(handle);
+    while (holds.length > HELD_SWFS) {
+      release(holds[0]);
+    }
+
+    return handle;
+  };
+  const actionsModule = (bytes: Uint8Array, actions: ActionBlocks, keep: boolean) => {
+    const [offsets, lengths] = ranges(actions);
+    const address = wasm.actionsModuleBytes(bytes, offsets, lengths, actions.version, keep);
+    return collected(handed(address, wasm.outputLength()));
+  };
+  // UTF-8 a call handed out in codegen's memory, not copied (see handOut in
+  // assembly/output.ts), decoded before anything else calls in: the next
+  // call may grow memory or move them, and a collection may free them.
+  const handed = (address: number, length: number) =>
+    length === 0 ? "" : utf8.decode(new Uint8Array(wasm.memory.buffer, address, length));
+  const stamps = WebAssembly.Module.customSections(module, "swf2es.build");
+  const identity = stamps.length ? String.fromCharCode(...new Uint8Array(stamps[0])) : null;
+  let epoch = 0;
+  let apiVersion = API_VERSION;
+  const collected = <T>(result: T, reclaim = false): T => {
+    const grown = wasm.memory.buffer.byteLength;
+    if (reclaim || grown > size || ++calls >= COLLECT_EVERY) {
+      wasm.__collect();
+      size = grown;
+      calls = 0;
+      methodBytes = 0;
+    }
+
+    return result;
+  };
+
+  return {
+    identity,
+    abcVersion(abc) {
+      const packed = collected(wasm.abcVersion(abc));
+      return packed < 0 ? null : { major: packed >>> 16, minor: packed & 0xffff };
+    },
+    get epoch() {
+      return epoch;
+    },
+    reset(version = API_VERSION) {
+      checkApiVersion(version);
+      added = 0;
+      epoch++;
+      apiVersion = version;
+      collected(wasm.domainReset(version));
+    },
+    get apiVersion() {
+      return apiVersion;
+    },
+    add(abc, builtin = false, appDomain = 0) {
+      const error = collected(wasm.domainAdd(abc, builtin, appDomain));
+      if (error < 0) {
+        throw new Error(`application domain ${appDomain}: never made, or dropped`);
+      }
+
+      if (error === 0) {
+        added++;
+      }
+
+      return error;
+    },
+    childDomain(parent) {
+      const domain = collected(wasm.domainChild(parent));
+      if (domain < 0) {
+        throw new Error(`application domain ${parent}: never made, or dropped`);
+      }
+
+      return domain;
+    },
+    dropDomain(appDomain, of = epoch) {
+      if (of === epoch) {
+        collected(wasm.domainDrop(appDomain));
+      }
+    },
+    evictDomain(appDomain) {
+      collected(wasm.domainEvict(appDomain));
+    },
+    usage() {
+      const [live, dead, memory] = collected(wasm.domainUsage()).split(" ").map(Number);
+      return { live, dead, memory };
+    },
+    compact() {
+      // A rebuild makes new tables while the old are live: what earlier
+      // calls left is collected first, and the old tables once it is done,
+      // before the next call's allocations would grow memory past them.
+      if (!collected(wasm.domainWantsCompact())) {
+        return false;
+      }
+
+      wasm.__collect();
+      calls = 0;
+      if (!wasm.domainCompact()) {
+        return false;
+      }
+
+      wasm.__collect();
+      size = wasm.memory.buffer.byteLength;
+      calls = 0;
+      return true;
+    },
+    isLive(appDomain) {
+      return collected(wasm.domainState(appDomain)) === 0;
+    },
+    reviveDomain(appDomain, abcs) {
+      // Its ABCs' bytes are copied into the compiler only if a rebuild let go of them.
+      let revived = collected(wasm.domainRevive(appDomain));
+      if (revived < 0) {
+        for (const [index, bytes] of abcs) {
+          const error = collected(wasm.domainRestore(index, bytes));
+          if (error !== 0) {
+            throw new Error(`ABC ${index}: not of an evicted domain, or rejected (${error})`);
+          }
+        }
+
+        revived = collected(wasm.domainRevive(appDomain));
+      }
+
+      if (revived < 0) {
+        throw new Error(
+          `application domain ${appDomain}: not evicted, its parent not live, or an ABC of it not given`,
+        );
+      }
+
+      if (revived > 0) {
+        wasm.__collect();
+        size = wasm.memory.buffer.byteLength;
+        calls = 0;
+      }
+    },
+    found(d) {
+      collected(wasm.domainFound(d.domain, d.nsKind, d.uri, d.name, d.abc, d.asType));
+    },
+    compile(hashes = [], index = -1) {
+      last("compile");
+      // Each part a call of its own, collected after it: the module's garbage
+      // is gone before its entries are written.
+      const module = moduleOf(hashes, index, true);
+      const sourceMap = collected(wasm.domainSourceMap());
+      const entries = parseEntries(collected(wasm.domainModuleEntries()));
+      return { module, sourceMap, entries };
+    },
+    compileModule(hashes = [], index = -1) {
+      last("compileModule");
+      return moduleOf(hashes, index, false);
+    },
+    compileLazyModule(hashes = [], index = -1) {
+      last("compileLazyModule");
+      return moduleOf(hashes, index, false, true);
+    },
+    context(index = -1, after = 0, upTo = -1) {
+      if (added === 0) {
+        return null;
+      }
+
+      const text = collected(wasm.domainContext(indexOf(index), after, upTo));
+      if (text === "") {
+        return null;
+      }
+
+      const first = text.indexOf("\n");
+      const second = text.indexOf("\n", first + 1);
+      const abcs = text.slice(0, first);
+      return {
+        abcs: abcs ? abcs.split(",").map(Number) : [],
+        own: Number(text.slice(first + 1, second < 0 ? text.length : second)),
+        log: second < 0 ? "" : text.slice(second + 1),
+      };
+    },
+    revision() {
+      return `${epoch} ${wasm.domainRevision()}`;
+    },
+    compileModuleLogged(hashes = [], index = -1) {
+      last("compileModuleLogged");
+      const mark = wasm.domainLogMark();
+      const module = moduleOf(hashes, index, false);
+      const log = collected(wasm.domainLogSince(mark, indexOf(index)));
+      return { module, log: log === "!" ? null : log };
+    },
+    replay(log, index = -1) {
+      last("replay");
+      return collected(wasm.domainReplay(log, indexOf(index)));
+    },
+    compileMethods(bodies, index = -1) {
+      last("compileMethods");
+      const indices = bodies.filter((b) => Number.isInteger(b) && b >= 0);
+      if (indices.length === 0) {
+        return new Map();
+      }
+
+      const address = wasm.domainEmitEachBytes(indices.join(","), true, indexOf(index));
+      const length = wasm.outputLength();
+      methodBytes += length;
+      const text = handed(address, length);
+      return parseEntries(collected(text, methodBytes >= COLLECT_METHOD_BYTES));
+    },
+    compileActions(bytes, actions) {
+      const module = actionsModule(bytes, actions, true);
+      const entries = parseEntries(collected(wasm.actionsModuleEntries()));
+      const units = new Map<string, ModuleUnit>();
+      for (const item of collected(wasm.actionsModuleUnits()).split("\u0002")) {
+        const [key, numbers, limits, code] = item.split("\u0001");
+        if (code !== undefined) {
+          const [at, end, bound, five] = numbers.split(",").map(Number);
+          const [high, reach] = limits.split(",").map(Number);
+          units.set(key, { code, high, reach, unit: { at, end, bound, five: five !== 0 } });
+        }
+      }
+
+      return { module, entries: actions.blocks.map((_, k) => entries.get(k) ?? ""), units };
+    },
+    compileActionsModule(bytes, actions) {
+      return actionsModule(bytes, actions, false);
+    },
+    compileActionBlocks(bytes, actions, blocks) {
+      const indices = blocks.filter((b) => Number.isInteger(b) && b >= 0);
+      if (indices.length === 0) {
+        return new Map();
+      }
+
+      // The SWF held, as for units: a block needs it whole, and copying it
+      // in for each block cost a copy of the SWF in codegen's memory
+      // beside the one held for units, and the time to copy it.
+      const handle = hold(bytes, actions);
+      const address = wasm.actionsHeldEmitEachBytes(handle, actions.version, indices.join(","));
+      const text = handed(address, wasm.outputLength());
+      // A block's analysis can go before the next block runs.
+      return parseEntries(collected(text, true));
+    },
+    compileActionUnit(bytes, actions, { at, end, bound, five }) {
+      const handle = hold(bytes, actions);
+      const address = wasm.actionsHeldUnitBytes(handle, actions.version, at, end, bound, five);
+      const code = handed(address, wasm.outputLength());
+      const [high, reach] = wasm.actionsUnitLimits();
+      return collected({ code, high, reach });
+    },
+    releaseActions(bytes) {
+      const known = holding.get(bytes);
+      if (known !== undefined) {
+        release(known.handle);
+        holding.delete(bytes);
+        collectedSwfs.unregister(known);
+      }
+    },
+    heldActions() {
+      return { held: collected(wasm.actionsHeldCount()), copies };
+    },
+  };
+}
+
+/** Entries as the wasm writes them: for each, the body's index, U+0001, its entry, U+0002. */
+function parseEntries(text: string): Map<number, string> {
+  const entries = new Map<number, string>();
+  for (const item of text.split("\u0002")) {
+    const at = item.indexOf("\u0001");
+    if (at > 0) {
+      entries.set(Number(item.slice(0, at)), item.slice(at + 1));
+    }
+  }
+
+  return entries;
+}
+
+const COLLECT_EVERY = 64;
+/** How many SWFs whose blocks or units are compiled codegen holds a copy of at most. */
+const HELD_SWFS = 4;
+// Large method entries should not accumulate sixty-four calls of garbage.
+const COLLECT_METHOD_BYTES = 256 * 1024;
+
+// TextDecoder is the web's and node's alike, though not ECMAScript's,
+// whose library alone the compiler's wrapper is typed against.
+declare const TextDecoder: new () => { decode(bytes: Uint8Array): string };
+
+const utf8 = new TextDecoder();