@soundscript/soundscript 0.1.13 → 0.1.15

package/project-transform/src/compiler_test_helpers.ts

@@ -0,0 +1,1087 @@
+import { assertEquals } from '@std/assert';
+import { dirname, fromFileUrl, join } from './platform/path.ts';
+import ts from 'typescript';
+
+import { createSoundStdlibCompilerHost } from './bundled/sound_stdlib.ts';
+import { compileProject } from './compiler/compile_project.ts';
+import type { CompilerModuleIR } from './compiler/ir.ts';
+import { lowerProgramToCompilerIR } from './compiler/lower.ts';
+import type {
+  CompilerRuntimeAdaptObjectValueIR,
+  CompilerRuntimeAllocateFallbackObjectIR,
+  CompilerRuntimeAllocateSpecializedObjectIR,
+  CompilerRuntimeGetFallbackObjectPropertyIR,
+  CompilerRuntimeGetSpecializedObjectFieldIR,
+  CompilerRuntimeSetFallbackObjectPropertyIR,
+  CompilerRuntimeSpecializedObjectRepresentationIR,
+} from './compiler/runtime_ir.ts';
+import { loadConfig } from './config.ts';
+import { instantiateSoundscriptWasmModule } from './compiler/wasm_js_host_runtime.ts';
+
+export interface TempProjectFile {
+  path: string;
+  contents: string;
+}
+
+const REPO_ROOT = dirname(dirname(fromFileUrl(import.meta.url)));
+const SOUNDSCRIPT_CLASS_TAG = '__soundscript_class_tag__';
+const SOUNDSCRIPT_CLASS_CONSTRUCT = '__soundscript_class_construct';
+const SOUNDSCRIPT_CLASS_BASE_CONSTRUCTOR = '__soundscript_class_base_constructor';
+const SOUNDSCRIPT_CLOSURE_REF = Symbol('soundscript_closure_ref');
+const SOUNDSCRIPT_SYNC_AWARE = Symbol('soundscript_sync_aware');
+const SOUNDSCRIPT_ISOLATED_TESTS = 'SOUNDSCRIPT_ISOLATED_TESTS';
+const SOUNDSCRIPT_ISOLATED_TEST_BATCH_SIZE = 'SOUNDSCRIPT_ISOLATED_TEST_BATCH_SIZE';
+const DEFAULT_ISOLATED_TEST_BATCH_SIZE = 8;
+
+let cachedCliTestFilterEnabled: boolean | undefined;
+
+function getConfiguredIsolatedTestBatchSize(): number {
+  const rawValue = Deno.env.get(SOUNDSCRIPT_ISOLATED_TEST_BATCH_SIZE);
+  if (rawValue === undefined) {
+    return DEFAULT_ISOLATED_TEST_BATCH_SIZE;
+  }
+  const parsed = Number.parseInt(rawValue, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_ISOLATED_TEST_BATCH_SIZE;
+}
+
+function getCliTestFilterEnabled(): boolean {
+  if (cachedCliTestFilterEnabled !== undefined) {
+    return cachedCliTestFilterEnabled;
+  }
+
+  const result = new Deno.Command('ps', {
+    args: ['-p', String(Deno.pid), '-o', 'command='],
+    stderr: 'piped',
+    stdout: 'piped',
+  }).outputSync();
+
+  if (!result.success) {
+    cachedCliTestFilterEnabled = true;
+    return cachedCliTestFilterEnabled;
+  }
+
+  const commandLine = new TextDecoder().decode(result.stdout);
+  cachedCliTestFilterEnabled = /(?:^|\s)(?:--filter|-f)(?:=|\s|$)/.test(commandLine);
+  return cachedCliTestFilterEnabled;
+}
+
+export function createIsolatedTestRegistrar(fileUrl: string) {
+  const isolatedTestNamesValue = Deno.env.get(SOUNDSCRIPT_ISOLATED_TESTS);
+  const isolatedTestNames = isolatedTestNamesValue === undefined
+    ? undefined
+    : JSON.parse(isolatedTestNamesValue) as string[];
+  const isolatedTestNameSet = isolatedTestNames === undefined
+    ? undefined
+    : new Set(isolatedTestNames);
+  const filePath = fromFileUrl(fileUrl);
+  const registeredTestNames: string[] = [];
+  const batchRuns = new Map<number, { ownerName: string; promise: Promise<void> }>();
+  const batchSize = isolatedTestNameSet === undefined && !getCliTestFilterEnabled()
+    ? getConfiguredIsolatedTestBatchSize()
+    : 1;
+
+  const runIsolatedTests = async (testNames: string[]) => {
+    const command = new Deno.Command(Deno.execPath(), {
+      args: [
+        'test',
+        '--no-check',
+        '--allow-env',
+        '--allow-read',
+        '--allow-write',
+        '--allow-run',
+        filePath,
+      ],
+      cwd: REPO_ROOT,
+      env: {
+        ...Deno.env.toObject(),
+        [SOUNDSCRIPT_ISOLATED_TESTS]: JSON.stringify(testNames),
+      },
+      stderr: 'piped',
+      stdout: 'piped',
+    });
+    const result = await command.output();
+    const stdout = new TextDecoder().decode(result.stdout);
+    const stderr = new TextDecoder().decode(result.stderr);
+    assertEquals(
+      result.success,
+      true,
+      [
+        `isolated compiler test batch failed: ${testNames.join(', ')}`,
+        `stdout:\n${stdout}`,
+        `stderr:\n${stderr}`,
+      ].join('\n\n'),
+    );
+  };
+
+  return (name: string, fn: () => Promise<void> | void): void => {
+    const testIndex = registeredTestNames.length;
+    registeredTestNames.push(name);
+
+    if (isolatedTestNameSet !== undefined && !isolatedTestNameSet.has(name)) {
+      return;
+    }
+
+    Deno.test({
+      name,
+      sanitizeOps: false,
+      sanitizeResources: false,
+      async fn() {
+        if (isolatedTestNameSet !== undefined) {
+          await fn();
+          return;
+        }
+
+        const batchId = Math.floor(testIndex / batchSize);
+        const existingBatchRun = batchRuns.get(batchId);
+        if (existingBatchRun !== undefined) {
+          if (existingBatchRun.ownerName !== name) {
+            try {
+              await existingBatchRun.promise;
+            } catch {
+              // Let the owner test report the batch failure once.
+            }
+          } else {
+            await existingBatchRun.promise;
+          }
+          return;
+        }
+
+        const batchStart = batchId * batchSize;
+        const batchEnd = batchStart + batchSize;
+        const batchTestNames = registeredTestNames.slice(batchStart, batchEnd);
+        const batchPromise = runIsolatedTests(batchTestNames);
+        batchRuns.set(batchId, { ownerName: name, promise: batchPromise });
+        await batchPromise;
+      },
+    });
+  };
+}
+
+export async function createTempProject(files: TempProjectFile[]): Promise<string> {
+  const tempDirectory = await Deno.makeTempDir({ prefix: 'sound-tsc-compiler-' });
+
+  for (const file of files) {
+    const absolutePath = join(tempDirectory, file.path);
+    await Deno.mkdir(dirname(absolutePath), { recursive: true });
+    await Deno.writeTextFile(absolutePath, file.contents);
+  }
+
+  return tempDirectory;
+}
+
+export function getOutputDirectory(tempDirectory: string): string {
+  return join(tempDirectory, 'soundscript-out');
+}
+
+export function getWatPath(tempDirectory: string): string {
+  return join(getOutputDirectory(tempDirectory), 'module.wat');
+}
+
+export async function readWatArtifact(tempDirectory: string): Promise<string> {
+  return await Deno.readTextFile(getWatPath(tempDirectory));
+}
+
+export async function readCompiledWasmBytes(tempDirectory: string): Promise<Uint8Array> {
+  const watPath = getWatPath(tempDirectory);
+  const wasmPath = join(getOutputDirectory(tempDirectory), 'module.test.wasm');
+  const command = new Deno.Command('wasm-tools', {
+    args: ['parse', watPath, '-o', wasmPath],
+    stderr: 'piped',
+    stdout: 'piped',
+  });
+  const result = await command.output();
+  if (!result.success) {
+    throw new Error(new TextDecoder().decode(result.stderr).trim());
+  }
+
+  return await Deno.readFile(wasmPath);
+}
+
+function createJsHostImports(
+  instanceCell: { instance: WebAssembly.Instance | null },
+): WebAssembly.Imports {
+  const heapIdentityCache = new WeakMap<object, unknown>();
+  const hostParamIdentityCache = new WeakMap<object, Map<string, unknown>>();
+  const hostPromiseToInternalCache = new WeakMap<object, object>();
+  const internalPromiseToHostCache = new WeakMap<object, Promise<unknown>>();
+  const classConstructorWrappers = new Map<number, Function>();
+  const getClassMethodSyncExportName = (tag: number, propertyName: string): string =>
+    `__soundscript_sync_class_method_${tag}__${
+      [...new TextEncoder().encode(propertyName)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('')
+    }`;
+  const getClassMethodSyncFromHostExportName = (tag: number, propertyName: string): string =>
+    `__soundscript_sync_from_class_method_${tag}__${
+      [...new TextEncoder().encode(propertyName)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('')
+    }`;
+  const getClassStaticMethodSyncExportName = (tag: number, propertyName: string): string =>
+    `__soundscript_sync_class_static_method_${tag}__${
+      [...new TextEncoder().encode(propertyName)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('')
+    }`;
+  const getClassStaticMethodSyncFromHostExportName = (tag: number, propertyName: string): string =>
+    `__soundscript_sync_from_class_static_method_${tag}__${
+      [...new TextEncoder().encode(propertyName)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('')
+    }`;
+
+  const expectHeapIdentityKey = (value: unknown): object => {
+    if (
+      (typeof value !== 'object' && typeof value !== 'function') ||
+      value === null
+    ) {
+      throw new TypeError('Expected wasm heap reference for host identity cache.');
+    }
+    return value;
+  };
+
+  const getOrCreateHostClassConstructor = (tag: number): Function => {
+    const existing = classConstructorWrappers.get(tag);
+    if (existing) {
+      return existing;
+    }
+    const wrapper = function SoundscriptClassWrapper(this: unknown, ...args: unknown[]): unknown {
+      if (new.target === undefined) {
+        throw new TypeError('Class constructors must be invoked with new.');
+      }
+      const construct =
+        (wrapper as unknown as Record<string, unknown>)[SOUNDSCRIPT_CLASS_CONSTRUCT];
+      if (typeof construct !== 'function') {
+        throw new TypeError('Compiled class constructor wrapper is missing construct hook.');
+      }
+      return construct(...args);
+    };
+    Object.defineProperty(wrapper, 'name', {
+      configurable: true,
+      value: `SoundscriptClass${tag}`,
+    });
+    Object.defineProperty(wrapper, Symbol.hasInstance, {
+      configurable: true,
+      value(instance: unknown) {
+        if (typeof instance !== 'object' || instance === null) {
+          return false;
+        }
+        return wrapper.prototype.isPrototypeOf(instance);
+      },
+    });
+    Object.defineProperty(wrapper.prototype, 'constructor', {
+      configurable: true,
+      enumerable: false,
+      value: wrapper,
+      writable: true,
+    });
+    Object.defineProperty(wrapper, SOUNDSCRIPT_CLASS_TAG, {
+      configurable: true,
+      enumerable: false,
+      value: Number(tag),
+      writable: true,
+    });
+    classConstructorWrappers.set(tag, wrapper);
+    return wrapper;
+  };
+
+  const syncClassPrototype = (value: unknown) => {
+    if (typeof value !== 'object' || value === null) {
+      throw new TypeError('Expected JS object for soundscript_object.sync_class_prototype.');
+    }
+    const objectRecord = value as Record<string, unknown>;
+    const tag = objectRecord[SOUNDSCRIPT_CLASS_TAG];
+    if (typeof tag !== 'number') {
+      return;
+    }
+    Object.setPrototypeOf(value, getOrCreateHostClassConstructor(Number(tag)).prototype);
+  };
+
+  const syncHostBoundaryValue = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        value[index] = syncHostBoundaryValue(value[index]);
+      }
+      return value;
+    }
+    if (typeof value === 'object' && value !== null) {
+      syncClassPrototype(value);
+    }
+    return value;
+  };
+
+  const wrapHostMethodIfNeeded = (
+    target: Record<string, unknown>,
+    propertyName: string,
+    value: unknown,
+  ): unknown => {
+    if (typeof value !== 'function') {
+      return value;
+    }
+    if ((value as unknown as Record<PropertyKey, unknown>)[SOUNDSCRIPT_SYNC_AWARE] === true) {
+      return value;
+    }
+    const tag = target[SOUNDSCRIPT_CLASS_TAG];
+    const closureRef = (value as unknown as Record<PropertyKey, unknown>)[SOUNDSCRIPT_CLOSURE_REF];
+    if (typeof tag !== 'number' || closureRef === undefined) {
+      return value;
+    }
+    const instance = instanceCell.instance;
+    if (!instance) {
+      return value;
+    }
+    const syncExportName = typeof target === 'function'
+      ? getClassStaticMethodSyncExportName(Number(tag), propertyName)
+      : getClassMethodSyncExportName(Number(tag), propertyName);
+    const syncFromHostExportName = typeof target === 'function'
+      ? getClassStaticMethodSyncFromHostExportName(Number(tag), propertyName)
+      : getClassMethodSyncFromHostExportName(Number(tag), propertyName);
+    const sync = instance.exports[syncExportName];
+    const syncFromHost = instance.exports[syncFromHostExportName];
+    if (typeof sync !== 'function' && typeof syncFromHost !== 'function') {
+      return value;
+    }
+    const callable = value as (...args: unknown[]) => unknown;
+    const wrapped = function (this: unknown, ...args: unknown[]): unknown {
+      if (typeof syncFromHost === 'function') {
+        syncFromHost(closureRef, target);
+      }
+      const result = callable.apply(this, args);
+      if (typeof sync === 'function') {
+        sync(closureRef, target);
+      }
+      return result;
+    };
+    Object.defineProperty(wrapped, SOUNDSCRIPT_CLOSURE_REF, {
+      configurable: true,
+      enumerable: false,
+      value: closureRef,
+      writable: false,
+    });
+    return wrapped;
+  };
+
+  return {
+    soundscript_array: {
+      empty: () => [],
+      empty_number: () => [],
+      empty_boolean: () => [],
+      clear: (value: unknown) => {
+        if (!Array.isArray(value)) {
+          throw new TypeError('Expected JS array for soundscript_array.clear.');
+        }
+        value.length = 0;
+      },
+      length: (value: unknown) => {
+        if (!Array.isArray(value)) {
+          throw new TypeError('Expected JS array for soundscript_array.length.');
+        }
+        return value.length;
+      },
+      same: (left: unknown, right: unknown) => Number(Object.is(left, right)),
+      get: (value: unknown, index: number) => {
+        if (!Array.isArray(value)) {
+          throw new TypeError('Expected JS array for soundscript_array.get.');
+        }
+        return value[Number(index)];
+      },
+      get_number: (value: unknown, index: number) => {
+        if (!Array.isArray(value)) {
+          throw new TypeError('Expected JS array for soundscript_array.get_number.');
+        }
+        return Number(value[Number(index)]);
+      },
+      get_boolean: (value: unknown, index: number) => {
+        if (!Array.isArray(value)) {
+          throw new TypeError('Expected JS array for soundscript_array.get_boolean.');
+        }
+        return Boolean(value[Number(index)]) ? 1 : 0;
+      },
+      push: (target: unknown, value: unknown) => {
+        if (!Array.isArray(target)) {
+          throw new TypeError('Expected JS array for soundscript_array.push.');
+        }
+        target.push(syncHostBoundaryValue(value));
+      },
+      push_number: (target: unknown, value: unknown) => {
+        if (!Array.isArray(target)) {
+          throw new TypeError('Expected JS array for soundscript_array.push_number.');
+        }
+        target.push(Number(value));
+      },
+      push_boolean: (target: unknown, value: unknown) => {
+        if (!Array.isArray(target)) {
+          throw new TypeError('Expected JS array for soundscript_array.push_boolean.');
+        }
+        target.push(Boolean(value));
+      },
+    },
+    soundscript_length_view: {
+      length: (value: unknown) => {
+        if (
+          value === null ||
+          value === undefined ||
+          (!Array.isArray(value) && typeof value !== 'string' &&
+            (typeof value !== 'object' || value === null || !('length' in value)))
+        ) {
+          throw new TypeError('Expected string, array, or length-bearing object.');
+        }
+        return Number((value as { length: unknown }).length);
+      },
+      from_length: (value: number) => ({ length: Number(value) }),
+    },
+    soundscript_object: new Proxy({}, {
+      get(_target, property) {
+        if (property === 'same') {
+          return (left: unknown, right: unknown) => Number(left === right);
+        }
+        if (property === 'empty') {
+          return () => ({});
+        }
+        if (property === 'lookup_cached') {
+          return (value: unknown) => heapIdentityCache.get(expectHeapIdentityKey(value)) ?? null;
+        }
+        if (property === 'remember_cached') {
+          return (value: unknown, hostValue: unknown) => {
+            heapIdentityCache.set(expectHeapIdentityKey(value), hostValue);
+          };
+        }
+        if (property === 'get_class_tag') {
+          return (value: unknown) => {
+            if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+              throw new TypeError(
+                'Expected JS object or function for soundscript_object.get_class_tag.',
+              );
+            }
+            const objectRecord = value as Record<string, unknown>;
+            return typeof objectRecord[SOUNDSCRIPT_CLASS_TAG] === 'number'
+              ? Number(objectRecord[SOUNDSCRIPT_CLASS_TAG])
+              : -1;
+          };
+        }
+        if (property === 'set_class_tag') {
+          return (value: unknown, next: number) => {
+            if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+              throw new TypeError(
+                'Expected JS object or function for soundscript_object.set_class_tag.',
+              );
+            }
+            Object.defineProperty(value, SOUNDSCRIPT_CLASS_TAG, {
+              configurable: true,
+              enumerable: false,
+              value: Number(next),
+              writable: true,
+            });
+          };
+        }
+        if (property === 'class_constructor_from_tag') {
+          return (tag: number) => getOrCreateHostClassConstructor(Number(tag));
+        }
+        if (property === 'sync_class_prototype') {
+          return syncClassPrototype;
+        }
+        if (typeof property !== 'string') {
+          return undefined;
+        }
+        const expectMapValue = (value: unknown): Map<unknown, unknown> => {
+          if (!(value instanceof Map)) {
+            throw new TypeError('Expected JS Map for soundscript_object collection host boundary.');
+          }
+          return value;
+        };
+        const expectSetValue = (value: unknown): Set<unknown> => {
+          if (!(value instanceof Set)) {
+            throw new TypeError('Expected JS Set for soundscript_object collection host boundary.');
+          }
+          return value;
+        };
+        if (property === 'map_keys') {
+          return (value: unknown) =>
+            Array.from(expectMapValue(value).keys(), (entry) => String(entry));
+        }
+        if (property === 'map_values_number') {
+          return (value: unknown) =>
+            Array.from(expectMapValue(value).values(), (entry) => Number(entry));
+        }
+        if (property === 'map_values_boolean') {
+          return (value: unknown) =>
+            Array.from(expectMapValue(value).values(), (entry) => Boolean(entry));
+        }
+        if (property === 'map_values_string') {
+          return (value: unknown) =>
+            Array.from(expectMapValue(value).values(), (entry) => String(entry));
+        }
+        if (property === 'set_values_number') {
+          return (value: unknown) =>
+            Array.from(expectSetValue(value).values(), (entry) => Number(entry));
+        }
+        if (property === 'set_values_boolean') {
+          return (value: unknown) =>
+            Array.from(expectSetValue(value).values(), (entry) => Boolean(entry));
+        }
+        if (property === 'set_values_string') {
+          return (value: unknown) =>
+            Array.from(expectSetValue(value).values(), (entry) => String(entry));
+        }
+        if (property === 'set_values_key') {
+          return () => '__set_values';
+        }
+        const match =
+          /^(get_number|get_boolean|get_closure|set_number|set_boolean|set_closure|has|get_tagged|set_tagged):(.*)$/
+            .exec(property);
+        const paramCacheMatch = /^(lookup_param_cached|remember_param_cached):(.*)$/.exec(property);
+        if (paramCacheMatch) {
+          const kind = paramCacheMatch[1];
+          const cacheKey = decodeURIComponent(paramCacheMatch[2]!);
+          const expectHostIdentityKey = (value: unknown): object => {
+            if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+              throw new TypeError(
+                'Expected JS object for soundscript_object param identity cache.',
+              );
+            }
+            return value;
+          };
+          if (kind === 'lookup_param_cached') {
+            return (value: unknown) =>
+              hostParamIdentityCache.get(expectHostIdentityKey(value))?.get(cacheKey) ?? null;
+          }
+          return (value: unknown, heapValue: unknown) => {
+            const hostKey = expectHostIdentityKey(value);
+            const existing = hostParamIdentityCache.get(hostKey);
+            if (existing) {
+              existing.set(cacheKey, heapValue);
+              return;
+            }
+            const created = new Map<string, unknown>();
+            created.set(cacheKey, heapValue);
+            hostParamIdentityCache.set(hostKey, created);
+          };
+        }
+        if (!match) {
+          return undefined;
+        }
+        const kind = match[1];
+        const propertyName = decodeURIComponent(match[2]);
+        const expectObjectRecord = (value: unknown): Record<string, unknown> => {
+          if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+            throw new TypeError(
+              'Expected JS object or function for soundscript_object host boundary.',
+            );
+          }
+          return value as Record<string, unknown>;
+        };
+        switch (kind) {
+          case 'has':
+            return (value: unknown) =>
+              Number(Object.prototype.hasOwnProperty.call(expectObjectRecord(value), propertyName));
+          case 'get_number':
+            return (value: unknown) => Number(expectObjectRecord(value)[propertyName]);
+          case 'get_boolean':
+            return (value: unknown) => Number(Boolean(expectObjectRecord(value)[propertyName]));
+          case 'get_closure':
+            return (value: unknown) => {
+              const objectRecord = expectObjectRecord(value);
+              const propertyValue = objectRecord[propertyName];
+              return typeof propertyValue === 'function'
+                ? propertyValue.bind(value)
+                : propertyValue;
+            };
+          case 'get_tagged':
+            return (value: unknown) => expectObjectRecord(value)[propertyName];
+          case 'set_number':
+            return (value: unknown, next: number) => {
+              expectObjectRecord(value)[propertyName] = Number(next);
+            };
+          case 'set_boolean':
+            return (value: unknown, next: number) => {
+              expectObjectRecord(value)[propertyName] = next !== 0;
+            };
+          case 'set_closure':
+            return (value: unknown, next: unknown) => {
+              const objectRecord = expectObjectRecord(value);
+              objectRecord[propertyName] = wrapHostMethodIfNeeded(objectRecord, propertyName, next);
+            };
+          case 'set_tagged':
+            return (value: unknown, next: unknown) => {
+              const objectRecord = expectObjectRecord(value);
+              objectRecord[propertyName] = syncHostBoundaryValue(next);
+              if (
+                propertyName === SOUNDSCRIPT_CLASS_BASE_CONSTRUCTOR &&
+                typeof value === 'function' &&
+                typeof next === 'function'
+              ) {
+                Object.setPrototypeOf(value, next);
+                if (
+                  typeof (value as { prototype?: unknown }).prototype === 'object' &&
+                  (value as { prototype?: unknown }).prototype !== null &&
+                  typeof (next as { prototype?: unknown }).prototype === 'object' &&
+                  (next as { prototype?: unknown }).prototype !== null
+                ) {
+                  Object.setPrototypeOf(
+                    (value as { prototype: object }).prototype,
+                    (next as { prototype: object }).prototype,
+                  );
+                }
+              }
+            };
+          default:
+            return undefined;
+        }
+      },
+    }),
+    soundscript_string: {
+      empty: () => '',
+      from_char_code: (value: number) => String.fromCharCode(Number(value)),
+      length: (value: unknown) => String(value).length,
+      char_at: (value: unknown, index: number) => String(value).charAt(Number(index)),
+      char_code_at: (value: unknown, index: number) => String(value).charCodeAt(Number(index)),
+      to_upper_case: (value: unknown) => String(value).toUpperCase(),
+      to_lower_case: (value: unknown) => String(value).toLowerCase(),
+      trim: (value: unknown) => String(value).trim(),
+      trim_start: (value: unknown) => String(value).trimStart(),
+      trim_end: (value: unknown) => String(value).trimEnd(),
+      starts_with: (value: unknown, search: unknown) =>
+        Number(String(value).startsWith(String(search))),
+      ends_with: (value: unknown, search: unknown) =>
+        Number(String(value).endsWith(String(search))),
+      includes: (value: unknown, search: unknown) => Number(String(value).includes(String(search))),
+      index_of: (value: unknown, search: unknown) => String(value).indexOf(String(search)),
+      last_index_of: (value: unknown, search: unknown) => String(value).lastIndexOf(String(search)),
+      slice: (value: unknown, start: number, end: number, hasEnd: number) =>
+        hasEnd
+          ? String(value).slice(Number(start), Number(end))
+          : String(value).slice(Number(start)),
+      substring: (value: unknown, start: number, end: number, hasEnd: number) =>
+        hasEnd
+          ? String(value).substring(Number(start), Number(end))
+          : String(value).substring(Number(start)),
+      concat: (left: unknown, right: unknown) => String(left) + String(right),
+      equals: (left: unknown, right: unknown) => Number(String(left) === String(right)),
+    },
+    soundscript_tagged: {
+      undefined_value: () => undefined,
+      type_tag: (value: unknown) => {
+        if (value === undefined) {
+          return 0;
+        }
+        if (typeof value === 'boolean') {
+          return 1;
+        }
+        if (typeof value === 'number') {
+          return 2;
+        }
+        if (typeof value === 'string') {
+          return 3;
+        }
+        if (typeof value === 'object' || typeof value === 'function') {
+          if (value === null) {
+            return 6;
+          }
+          return 4;
+        }
+        if (value === null) {
+          return 6;
+        }
+        throw new Error(`Unsupported tagged host value: ${String(value)}`);
+      },
+      number_value: (value: unknown) => Number(value),
+      boolean_value: (value: unknown) => Number(Boolean(value)),
+      from_number: (value: number) => Number(value),
+      from_boolean: (value: number) => value !== 0,
+    },
+    soundscript_closure: new Proxy({}, {
+      get(_target, property) {
+        if (typeof property !== 'string') {
+          return undefined;
+        }
+        const callMatch = /^call_(\d+)$/.exec(property);
+        if (callMatch) {
+          return (callback: unknown, ...args: unknown[]) => {
+            if (typeof callback !== 'function') {
+              throw new TypeError('Expected JS function for soundscript_closure.call.');
+            }
+            return callback(...args);
+          };
+        }
+        const toHostSyncMatch = /^to_host_sync_(\d+):(.*)$/.exec(property);
+        if (toHostSyncMatch) {
+          const signatureId = Number(toHostSyncMatch[1]);
+          const syncExportName = decodeURIComponent(toHostSyncMatch[2] ?? '');
+          return (target: unknown, closure: unknown) => {
+            const wrapped = (...args: unknown[]) => {
+              const instance = instanceCell.instance;
+              if (!instance) {
+                throw new Error('Closure export wrapper invoked before instantiation completed.');
+              }
+              const invoke = instance.exports[`__soundscript_closure_invoke_${signatureId}`];
+              if (typeof invoke !== 'function') {
+                throw new Error(`Missing exported closure invoker for signature ${signatureId}.`);
+              }
+              const sync = instance.exports[syncExportName];
+              if (typeof sync !== 'function') {
+                throw new Error(`Missing exported closure sync helper ${syncExportName}.`);
+              }
+              const syncFromHostExportName =
+                syncExportName.startsWith('__soundscript_sync_class_method_')
+                  ? syncExportName.replace(
+                    '__soundscript_sync_class_method_',
+                    '__soundscript_sync_from_class_method_',
+                  )
+                  : syncExportName.startsWith('__soundscript_sync_class_static_method_')
+                  ? syncExportName.replace(
+                    '__soundscript_sync_class_static_method_',
+                    '__soundscript_sync_from_class_static_method_',
+                  )
+                  : null;
+              const syncFromHost = syncFromHostExportName
+                ? instance.exports[syncFromHostExportName]
+                : undefined;
+              if (typeof syncFromHost === 'function') {
+                syncFromHost(closure, target);
+              }
+              const result = invoke(closure, ...args);
+              sync(closure, target);
+              return result;
+            };
+            Object.defineProperty(wrapped, SOUNDSCRIPT_CLOSURE_REF, {
+              configurable: true,
+              enumerable: false,
+              value: closure,
+              writable: false,
+            });
+            Object.defineProperty(wrapped, SOUNDSCRIPT_SYNC_AWARE, {
+              configurable: true,
+              enumerable: false,
+              value: true,
+              writable: false,
+            });
+            return wrapped;
+          };
+        }
+        const toHostMatch = /^to_host_(\d+)$/.exec(property);
+        if (toHostMatch) {
+          const signatureId = Number(toHostMatch[1]);
+          return (closure: unknown) => {
+            const wrapped = (...args: unknown[]) => {
+              const instance = instanceCell.instance;
+              if (!instance) {
+                throw new Error('Closure export wrapper invoked before instantiation completed.');
+              }
+              const invoke = instance.exports[`__soundscript_closure_invoke_${signatureId}`];
+              if (typeof invoke !== 'function') {
+                throw new Error(`Missing exported closure invoker for signature ${signatureId}.`);
+              }
+              return invoke(closure, ...args);
+            };
+            Object.defineProperty(wrapped, SOUNDSCRIPT_CLOSURE_REF, {
+              configurable: true,
+              enumerable: false,
+              value: closure,
+              writable: false,
+            });
+            return wrapped;
+          };
+        }
+        return undefined;
+      },
+    }),
+    soundscript_promise: {
+      to_internal: (value: unknown, candidate: unknown) => {
+        if (!(value instanceof Promise)) {
+          throw new TypeError('Expected JS Promise for soundscript_promise.to_internal.');
+        }
+        const candidateKey = expectHeapIdentityKey(candidate);
+        const existing = hostPromiseToInternalCache.get(value);
+        if (existing) {
+          return existing;
+        }
+        const instance = instanceCell.instance;
+        if (!instance) {
+          throw new Error('Promise bridge invoked before instantiation completed.');
+        }
+        const fulfill = instance.exports.__soundscript_promise_bridge_fulfill;
+        const reject = instance.exports.__soundscript_promise_bridge_reject;
+        if (typeof fulfill !== 'function' || typeof reject !== 'function') {
+          throw new Error('Missing exported Promise bridge helpers.');
+        }
+        hostPromiseToInternalCache.set(value, candidateKey);
+        internalPromiseToHostCache.set(candidateKey, value);
+        value.then(
+          (resolved) => {
+            fulfill(candidateKey, resolved);
+          },
+          (reason) => {
+            reject(candidateKey, reason);
+          },
+        );
+        return candidateKey;
+      },
+      to_host: (value: unknown) => {
+        const internalPromise = expectHeapIdentityKey(value);
+        const existing = internalPromiseToHostCache.get(internalPromise);
+        if (existing) {
+          return existing;
+        }
+        const instance = instanceCell.instance;
+        if (!instance) {
+          throw new Error('Promise bridge invoked before instantiation completed.');
+        }
+        const attach = instance.exports.__soundscript_promise_then_host;
+        if (typeof attach !== 'function') {
+          throw new Error('Missing exported Promise host attachment helper.');
+        }
+        const created = new Promise<unknown>((resolve, reject) => {
+          attach(internalPromise, resolve, reject);
+        });
+        internalPromiseToHostCache.set(internalPromise, created);
+        return created;
+      },
+    },
+  };
+}
+
+export async function instantiateCompiledModuleInJs(
+  tempDirectory: string,
+  options?: {
+    hostFunctions?: Record<string, (...args: unknown[]) => unknown>;
+  },
+): Promise<WebAssembly.Instance> {
+  const wasmBytes = await readCompiledWasmBytes(tempDirectory);
+  return await instantiateSoundscriptWasmModule(wasmBytes, {
+    hostFunctions: options?.hostFunctions,
+  });
+}
+
+export async function readWatArtifactForProject(projectDirectory: string): Promise<string> {
+  return await Deno.readTextFile(join(projectDirectory, 'soundscript-out', 'module.wat'));
+}
+
+export async function resolveQualifiedExportName(
+  tempDirectory: string,
+  entry: string,
+): Promise<string> {
+  const wat = await readWatArtifact(tempDirectory);
+  const exportNames = [...wat.matchAll(/\(export "([^"]+)"\)/g)].map((match) => match[1]);
+
+  if (exportNames.includes(entry)) {
+    return entry;
+  }
+
+  const qualifiedMatches = exportNames.filter((name) => name.endsWith(`:${entry}`));
+  if (qualifiedMatches.length === 1) {
+    return qualifiedMatches[0];
+  }
+  if (qualifiedMatches.length > 1) {
+    throw new Error(`Ambiguous exported function "${entry}".`);
+  }
+
+  throw new Error(`Expected exported function "${entry}".`);
+}
+
+export async function invokeCompiledEntry(
+  tempDirectory: string,
+  entry: string,
+  args: number[],
+): Promise<number> {
+  const exportName = await resolveQualifiedExportName(tempDirectory, entry);
+  const instance = await instantiateCompiledModuleInJs(tempDirectory);
+  const exported = instance.exports[exportName];
+  if (typeof exported !== 'function') {
+    throw new Error(`Expected exported function "${exportName}".`);
+  }
+  const result = exported(...args);
+  const value = Number(result);
+  if (Number.isNaN(value)) {
+    throw new Error(`Expected numeric export result, received "${String(result)}".`);
+  }
+  return value;
+}
+
+export function createCompilerProgram(projectPath: string): ts.Program {
+  const loadedConfig = loadConfig(projectPath);
+  const host = createSoundStdlibCompilerHost(loadedConfig.commandLine.options);
+  return ts.createProgram({
+    host,
+    rootNames: loadedConfig.commandLine.fileNames,
+    options: loadedConfig.commandLine.options,
+    projectReferences: loadedConfig.commandLine.projectReferences,
+    configFileParsingDiagnostics: loadedConfig.diagnostics,
+  });
+}
+
+export function lowerTempProjectToCompilerIR(tempDirectory: string): CompilerModuleIR {
+  const projectPath = join(tempDirectory, 'tsconfig.json');
+  const program = createCompilerProgram(projectPath);
+  return lowerProgramToCompilerIR(program, dirname(projectPath));
+}
+
+export function compileCheckedInProject(relativeProjectDirectory: string) {
+  const projectDirectory = join(REPO_ROOT, relativeProjectDirectory);
+  return {
+    projectDirectory,
+    result: compileProject({
+      projectPath: join(projectDirectory, 'tsconfig.json'),
+      workingDirectory: projectDirectory,
+    }),
+  };
+}
+
+export function lowerCheckedInProjectToCompilerIR(
+  relativeProjectDirectory: string,
+): CompilerModuleIR {
+  const projectDirectory = join(REPO_ROOT, relativeProjectDirectory);
+  const program = createCompilerProgram(join(projectDirectory, 'tsconfig.json'));
+  return lowerProgramToCompilerIR(program, projectDirectory);
+}
+
+export function getAllRuntimeOperations(moduleIR: CompilerModuleIR) {
+  return moduleIR.runtime?.functions.flatMap((runtimeFunction) => runtimeFunction.operations) ?? [];
+}
+
+export function assertExecutableOrdinaryObjectLowering(
+  moduleIR: CompilerModuleIR,
+  options: {
+    shapeName: string;
+    fieldNames: string[];
+    allocationCount: number;
+    fieldReadIndices: number[];
+  },
+): {
+  allocations: CompilerRuntimeAllocateSpecializedObjectIR[];
+  fieldReads: CompilerRuntimeGetSpecializedObjectFieldIR[];
+  representation: CompilerRuntimeSpecializedObjectRepresentationIR;
+} {
+  if (!moduleIR.runtime) {
+    throw new Error('Expected lowering to produce runtime IR.');
+  }
+
+  const representation = moduleIR.runtime.representations.find((
+    runtimeRepresentation,
+  ): runtimeRepresentation is CompilerRuntimeSpecializedObjectRepresentationIR =>
+    runtimeRepresentation.kind === 'specialized_object_representation' &&
+    runtimeRepresentation.name === options.shapeName
+  );
+  if (!representation) {
+    throw new Error(`Expected specialized object representation ${options.shapeName}.`);
+  }
+
+  const operations = getAllRuntimeOperations(moduleIR);
+  const allocations = operations.filter((
+    operation,
+  ): operation is CompilerRuntimeAllocateSpecializedObjectIR =>
+    operation.kind === 'allocate_specialized_object'
+  );
+  const fieldReads = operations.filter((
+    operation,
+  ): operation is CompilerRuntimeGetSpecializedObjectFieldIR =>
+    operation.kind === 'get_specialized_object_field'
+  );
+
+  assertEquals(
+    operations.filter((operation) =>
+      operation.kind === 'adapt_value' && operation.family === 'object'
+    ).length,
+    0,
+  );
+  assertEquals(representation.fields.map((field) => field.name), options.fieldNames);
+  assertEquals(allocations.length, options.allocationCount);
+  assertEquals(fieldReads.map((operation) => operation.fieldIndex), options.fieldReadIndices);
+  assertEquals(
+    allocations.every((operation) => operation.representation.name === options.shapeName),
+    true,
+  );
+  assertEquals(
+    fieldReads.every((operation) => operation.representation.name === options.shapeName),
+    true,
+  );
+
+  return { allocations, fieldReads, representation };
+}
+
+export function assertObjectGeneralizationLowering(
+  moduleIR: CompilerModuleIR,
+  options: {
+    shapeName: string;
+    generalizationCount: number;
+  },
+): {
+  allocations: CompilerRuntimeAllocateSpecializedObjectIR[];
+  generalizations: CompilerRuntimeAdaptObjectValueIR[];
+  representation: CompilerRuntimeSpecializedObjectRepresentationIR;
+} {
+  if (!moduleIR.runtime) {
+    throw new Error('Expected lowering to produce runtime IR.');
+  }
+
+  const representation = moduleIR.runtime.representations.find((
+    runtimeRepresentation,
+  ): runtimeRepresentation is CompilerRuntimeSpecializedObjectRepresentationIR =>
+    runtimeRepresentation.kind === 'specialized_object_representation' &&
+    runtimeRepresentation.name === options.shapeName
+  );
+  if (!representation) {
+    throw new Error(`Expected specialized object representation ${options.shapeName}.`);
+  }
+
+  const operations = getAllRuntimeOperations(moduleIR);
+  const allocations = operations.filter((
+    operation,
+  ): operation is CompilerRuntimeAllocateSpecializedObjectIR =>
+    operation.kind === 'allocate_specialized_object'
+  );
+  const generalizations = operations.filter((
+    operation,
+  ): operation is CompilerRuntimeAdaptObjectValueIR =>
+    operation.kind === 'adapt_value' && operation.family === 'object'
+  );
+
+  assertEquals(
+    allocations.every((operation) => operation.representation.name === options.shapeName),
+    true,
+  );
+  assertEquals(generalizations.length, options.generalizationCount);
+  assertEquals(
+    generalizations.every((operation) =>
+      operation.fromRepresentation.name === options.shapeName &&
+      operation.toRepresentation.name === 'object.fallback'
+    ),
+    true,
+  );
+
+  return { allocations, generalizations, representation };
+}
+
+export function assertFallbackObjectRuntimeOperations(moduleIR: CompilerModuleIR): {
+  allocations: CompilerRuntimeAllocateFallbackObjectIR[];
+  generalizations: CompilerRuntimeAdaptObjectValueIR[];
+  propertyGets: CompilerRuntimeGetFallbackObjectPropertyIR[];
+  propertySets: CompilerRuntimeSetFallbackObjectPropertyIR[];
+} {
+  if (!moduleIR.runtime) {
+    throw new Error('Expected lowering to produce runtime IR.');
+  }
+
+  const operations = getAllRuntimeOperations(moduleIR);
+  return {
+    allocations: operations.filter((
+      operation,
+    ): operation is CompilerRuntimeAllocateFallbackObjectIR =>
+      operation.kind === 'allocate_fallback_object'
+    ),
+    generalizations: operations.filter((
+      operation,
+    ): operation is CompilerRuntimeAdaptObjectValueIR =>
+      operation.kind === 'adapt_value' && operation.family === 'object'
+    ),
+    propertyGets: operations.filter((
+      operation,
+    ): operation is CompilerRuntimeGetFallbackObjectPropertyIR =>
+      operation.kind === 'get_fallback_object_property'
+    ),
+    propertySets: operations.filter((
+      operation,
+    ): operation is CompilerRuntimeSetFallbackObjectPropertyIR =>
+      operation.kind === 'set_fallback_object_property'
+    ),
+  };
+}