@unicity-astrid/build 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @unicity-astrid/build
+
+[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](../../LICENSE-MIT)
+[![Node: >=20](https://img.shields.io/badge/Node-%3E%3D20-blue)](https://nodejs.org)
+
+**The compiler that turns a TypeScript class into a WASM capsule.**
+
+JavaScript counterpart of [`astrid-sdk-macros`](https://github.com/unicity-astrid/sdk-rust/tree/main/astrid-sdk-macros). Rust uses a proc macro that runs at `cargo build` time; JavaScript needs the same work done by external tooling that runs at `astrid build` time. This package is that tooling.
+
+Do not depend on this package directly from capsule code. It is invoked by the Rust kernel's `astrid-build` binary when it detects a `package.json + Capsule.toml` project, and emits the `wasm32-wasip2` component that the Rust side packs into the `.capsule` archive.
+
+## Pipeline
+
+```
+sdk-js/packages/astrid-build/src/index.mjs <project-dir> --out <wasm-path>
+
+1. Read package.json (name, version)
+2. wit-events codegen: walk project/wit/, emit project/gen/*.d.ts mirroring `wit_events!`
+3. tsc: compile src/*.ts → dist/*.js, using project's tsconfig.json
+4. Emit gen/_entry.src.mjs that imports the user's compiled entry,
+   constructs the SDK bridge, re-exports the four WIT export names
+5. esbuild bundle: gen/_entry.src.mjs + @unicity-astrid/sdk → gen/_entry.mjs
+   (one self-contained ESM file, "astrid:*" specifiers marked external)
+6. ComponentizeJS programmatic API: gen/_entry.mjs + wit/ → target/<name>.wasm
+   (with disableFeatures: all five, so the output has zero WASI imports)
+7. Print {wasmPath, bytes} as the final stdout line for the caller to parse
+```
+
+The Rust `astrid-build` then calls `pack_capsule_archive` on the resulting `.wasm` to produce a `dist/<name>.capsule` archive structurally identical to a Rust-built capsule.
+
+## What the bridge generates
+
+The `gen/_entry.mjs` is a thin wrapper that:
+
+- **Imports the user code** (decorators fire and populate the SDK registry)
+- **Builds the bridge** via `createBridge()` from `@unicity-astrid/sdk/runtime`
+- **Re-exports the four WIT-required guest functions**: `astridHookTrigger`, `run`, `astridInstall`, `astridUpgrade`
+
+The bridge runtime in `@unicity-astrid/sdk` dispatches:
+
+- `tool_describe` → lazy-built aggregated schema list (`{ tools: [...], description: "..." }`)
+- `tool_execute_<name>` → optional KV `__state` load → user handler → optional state save → IPC publish to `tool.v1.execute.<name>.result` → return `{ action: "continue", data: undefined }`
+- interceptor topic name → user handler → return result via `capsule-result.data`
+- command name → same as interceptor
+
+This mirrors `astrid-sdk-macros::capsule_impl` exactly, including the runnable-vs-hook-driven duality from `#[astrid::run]`.
+
+## Compile-time enforcement
+
+Decorator violations are caught at **registration time** (when the class first evaluates), not deferred to runtime:
+
+- Two `@install` methods on one class → throws at module load
+- Two `@upgrade` methods → throws
+- Two `@run` methods → throws
+- Two `@tool("name")` with the same name → throws
+- Two `@interceptor("topic")` with the same topic → throws
+- `@install` / `@upgrade` / `@run` on a private or static method → throws
+
+Schema input types are typechecked by `tsc` at build time. WIT event types are checked against generated `gen/<file>.d.ts`.
+
+## Configuration
+
+The orchestrator currently accepts:
+
+| Flag | Description |
+|---|---|
+| `<project-dir>` | Path to the capsule project (required) |
+| `--out <wasm-path>` | Where to write the componentized wasm (defaults to `<project>/target/<name>.wasm`) |
+
+The Rust kernel locates this script via:
+
+1. `$ASTRID_JS_BUILD` environment variable (absolute path override, dev-only)
+2. `<project>/node_modules/@unicity-astrid/build/src/index.mjs` (walked up like Node's resolver, so npm-workspaces hoisting works)
+
+## ComponentizeJS configuration
+
+The orchestrator pins:
+
+- `worldName: "capsule"` (the world declared in `astrid-capsule.wit`)
+- `disableFeatures: ["stdio", "random", "clocks", "http", "fetch-event"]` — strips all WASI imports so the kernel doesn't need to provide WASI. Without this, the component would fail to instantiate against the kernel's linker.
+
+These are not configurable — they are correctness requirements, not options.
+
+## Development
+
+```bash
+npm install
+node src/index.mjs ../../examples/test-capsule
+```
+
+## License
+
+Dual MIT/Apache-2.0. See [LICENSE-MIT](../../LICENSE-MIT) and [LICENSE-APACHE](../../LICENSE-APACHE).

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@unicity-astrid/build",
+  "version": "0.1.0",
+  "description": "Build orchestrator that turns a TS/JS Astrid capsule project into a wasm32-wasip2 component.",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "bin": {
+    "astrid-js-build": "./src/index.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "echo 'no build step — pure ESM'"
+  },
+  "dependencies": {
+    "@bytecodealliance/componentize-js": "^0.18.0",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,481 @@
+#!/usr/bin/env node
+/**
+ * Astrid JS/TS capsule build orchestrator.
+ *
+ * Invoked by `core/crates/astrid-build/src/js.rs`. Reads a project
+ * directory, produces a wasm32-wasip2 component.
+ *
+ * Pipeline:
+ *   1. Read package.json metadata (name, version, main / source entry).
+ *   2. tsc compile the project (if tsconfig.json present).
+ *   3. Resolve the SDK's `wit/` directory so componentize sees astrid-capsule.wit.
+ *   4. Emit gen/_entry.mjs: imports the user's compiled entry (decorators
+ *      fire), constructs the bridge, re-exports the four WIT export names.
+ *   5. Bundle gen/_entry.mjs (resolves @unicity-astrid/sdk into the bundle so
+ *      componentize sees one self-contained ESM file).
+ *   6. Invoke ComponentizeJS programmatic API.
+ *   7. Write the .wasm to the requested output path.
+ *
+ * CLI: `astrid-js-build <project-dir> --out <wasm-path>`
+ */
+
+import { componentize } from "@bytecodealliance/componentize-js";
+import * as esbuild from "esbuild";
+import { codegenWitEvents } from "./wit-codegen.mjs";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile, stat, rm, copyFile, readdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import ts from "typescript";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SDK_PKG_DIR = resolve(HERE, "..", "..", "astrid-sdk");
+// Canonical host ABI lives in the unicity-astrid/wit submodule (mounted at
+// repo-root/contracts/). Post per-domain WIT split (PR #752), each domain
+// is a separate `astrid:<domain>/host@1.0.0` package plus the foundation
+// `astrid:io/*@1.0.0` interfaces; componentize-js resolves the world the
+// capsule declares by reading every file in this directory.
+const REPO_ROOT = resolve(HERE, "..", "..", "..");
+const CANONICAL_WIT_DIR = resolve(REPO_ROOT, "contracts", "host");
+
+function die(msg) {
+  console.error(`astrid-js-build: ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  if (argv.length < 1) die("usage: astrid-js-build <project-dir> [--out <wasm-path>]");
+  const projectDir = resolve(argv[0]);
+  let out;
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === "--out" && i + 1 < argv.length) {
+      out = resolve(argv[++i]);
+    } else {
+      die(`unknown argument: ${argv[i]}`);
+    }
+  }
+  return { projectDir, out };
+}
+
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (err) {
+    die(`failed to read ${path}: ${err.message}`);
+  }
+}
+
+async function resolveProjectMetadata(projectDir) {
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) die(`no package.json at ${pkgPath}`);
+  const pkg = await readJson(pkgPath);
+  if (typeof pkg.name !== "string" || pkg.name.length === 0) {
+    die("package.json must have a non-empty 'name'");
+  }
+  return { name: pkg.name, version: pkg.version ?? "0.0.0", pkg };
+}
+
+function compileTypeScript(projectDir) {
+  const tsconfigPath = join(projectDir, "tsconfig.json");
+  if (!existsSync(tsconfigPath)) {
+    console.log("astrid-js-build: no tsconfig.json — skipping tsc compile");
+    return null;
+  }
+  // Use tsc CLI for full project-references support. The programmatic API
+  // would require us to re-implement project references; the CLI is the
+  // contract-tested path.
+  const tscBin = createRequire(import.meta.url).resolve("typescript/bin/tsc");
+  const result = spawnSync(process.execPath, [tscBin, "-p", projectDir], { stdio: "inherit" });
+  if (result.status !== 0) die("tsc failed");
+  // Read tsconfig to find outDir.
+  const raw = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+  if (raw.error) die(`tsconfig parse error: ${raw.error.messageText}`);
+  const parsed = ts.parseJsonConfigFileContent(raw.config, ts.sys, projectDir);
+  return parsed.options.outDir ?? join(projectDir, "dist");
+}
+
+function resolveEntry(projectDir, outDir) {
+  // Prefer compiled JS in outDir; fall back to package.json main.
+  const candidates = [
+    outDir ? join(outDir, "index.js") : undefined,
+    join(projectDir, "dist", "index.js"),
+    join(projectDir, "index.js"),
+    join(projectDir, "index.mjs"),
+  ].filter(Boolean);
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  die("could not locate compiled entry. Expected dist/index.js after tsc or index.js/.mjs at project root.");
+}
+
+function resolveSdkRuntime() {
+  const candidate = join(SDK_PKG_DIR, "dist", "runtime", "index.js");
+  if (!existsSync(candidate)) {
+    die(
+      `SDK runtime not found at ${candidate}. ` +
+        `Build @unicity-astrid/sdk first (npx tsc -b packages/astrid-sdk in the workspace root).`,
+    );
+  }
+  return candidate;
+}
+
+async function emitEntry(projectDir, userEntry) {
+  const genDir = join(projectDir, "gen");
+  await mkdir(genDir, { recursive: true });
+  const entryPath = join(genDir, "_entry.src.mjs");
+
+  // ComponentizeJS's splicer rejects file:// URL imports — it treats the
+  // entire URL as a relative path. Use POSIX-style relative paths instead.
+  const userEntryRel = posixRelative(genDir, userEntry);
+  const sdkRuntimeRel = posixRelative(genDir, resolveSdkRuntime());
+
+  const entrySource = `// Auto-generated by @unicity-astrid/build. Do not edit by hand.
+//
+// This file gets bundled with esbuild before componentize. Importing the
+// user module fires the @capsule / @tool / @install / @upgrade decorators,
+// which populate the SDK registry. We then build the bridge and re-export
+// the four WIT-required guest export names.
+
+import "${userEntryRel}";
+import { createBridge } from "${sdkRuntimeRel}";
+
+const bridge = createBridge();
+
+export function astridHookTrigger(action, payload) {
+  return bridge.astridHookTrigger(action, payload);
+}
+
+export function run() {
+  bridge.run();
+}
+
+export function astridInstall() {
+  bridge.astridInstall();
+}
+
+export function astridUpgrade() {
+  bridge.astridUpgrade();
+}
+`;
+  await writeFile(entryPath, entrySource);
+  return entryPath;
+}
+
+/**
+ * Bundle the generated entry into a single ESM file. ComponentizeJS can't
+ * resolve bare-specifier imports (`@unicity-astrid/sdk`); esbuild inlines
+ * everything except the WIT-resolved `astrid:*` imports.
+ */
+/**
+ * esbuild plugin that resolves Node builtins (`fs`, `path`, `crypto`,
+ * `zlib`, …) and a small allowlist of Node-flavoured packages (`ws`)
+ * to a synthetic module that returns throw-on-call Proxies for every
+ * access. The capsule runtime (StarlingMonkey) doesn't provide
+ * `node:*` builtins; libraries written for both Node and the browser
+ * commonly carry a `node:crypto` import for paths that never run on
+ * non-Node platforms. Without this plugin, those imports fail the
+ * bundle. With it, the bundle succeeds and any unreached path stays
+ * unreached at runtime — the proxy throws if a capsule actually
+ * touches them.
+ *
+ * Throwing lazily (on first call, not on import) matters: many
+ * sphere-sdk classes bind `crypto.createHmac` at top level via
+ * destructuring, but only call it down a code path that's never
+ * exercised in the capsule's actual usage (admin tooling, etc).
+ */
+function nodeBuiltinStubPlugin() {
+  // Per-module named-export lists. esbuild does static analysis of
+  // named imports against the stub module's actual exports, so the
+  // stub file must explicitly declare every name that could be
+  // destructure-imported by an upstream library. Growing this list
+  // is benign — unused entries cost nothing at bundle or runtime.
+  // Add new entries when a build surfaces "No matching export in
+  // 'astrid-node-stub:<X>' for import 'Y'".
+  const namedExports = {
+    assert: ["ok", "strict", "strictEqual", "deepEqual", "deepStrictEqual", "notEqual", "fail"],
+    buffer: ["Buffer", "Blob", "File", "constants", "kMaxLength", "kStringMaxLength", "atob", "btoa", "isAscii", "isUtf8"],
+    child_process: ["spawn", "spawnSync", "exec", "execSync", "execFile", "execFileSync", "fork"],
+    constants: [],
+    crypto: ["createHmac", "createHash", "createCipher", "createCipheriv", "createDecipher", "createDecipheriv", "createSign", "createVerify", "createDiffieHellman", "createECDH", "randomBytes", "randomUUID", "randomInt", "randomFillSync", "scrypt", "scryptSync", "pbkdf2", "pbkdf2Sync", "timingSafeEqual", "constants", "webcrypto", "subtle", "X509Certificate", "KeyObject", "generateKeySync", "generateKey", "generateKeyPair", "generateKeyPairSync", "createPublicKey", "createPrivateKey", "createSecretKey", "sign", "verify", "publicEncrypt", "privateDecrypt", "privateEncrypt", "publicDecrypt", "hkdf", "hkdfSync", "getCiphers", "getHashes", "getCurves", "getRandomValues"],
+    dgram: ["createSocket", "Socket"],
+    dns: ["lookup", "resolve", "resolve4", "resolve6", "resolveTxt", "promises"],
+    events: ["EventEmitter", "once", "on", "captureRejectionSymbol", "defaultMaxListeners", "errorMonitor", "setMaxListeners"],
+    fs: ["readFileSync", "writeFileSync", "existsSync", "statSync", "lstatSync", "readdirSync", "mkdirSync", "rmSync", "rmdirSync", "unlinkSync", "renameSync", "promises", "constants", "createReadStream", "createWriteStream", "watch", "watchFile", "openSync", "closeSync", "readSync", "writeSync", "fstatSync", "ftruncateSync", "appendFileSync", "accessSync", "copyFileSync", "linkSync", "symlinkSync", "readlinkSync", "realpathSync", "utimesSync", "chmodSync", "chownSync"],
+    "fs/promises": ["readFile", "writeFile", "stat", "lstat", "readdir", "mkdir", "rm", "rmdir", "unlink", "rename", "open", "access", "copyFile", "appendFile", "link", "symlink", "readlink", "realpath", "utimes", "chmod", "chown"],
+    http: ["createServer", "request", "get", "Agent", "globalAgent", "STATUS_CODES", "METHODS"],
+    https: ["createServer", "request", "get", "Agent", "globalAgent"],
+    module: ["createRequire", "builtinModules", "Module", "isBuiltin"],
+    net: ["createServer", "createConnection", "connect", "Socket", "Server", "isIP", "isIPv4", "isIPv6"],
+    os: ["arch", "platform", "type", "release", "hostname", "homedir", "tmpdir", "cpus", "endianness", "freemem", "totalmem", "uptime", "userInfo", "EOL", "constants"],
+    path: ["join", "resolve", "basename", "dirname", "extname", "sep", "delimiter", "isAbsolute", "normalize", "relative", "parse", "format", "posix", "win32", "toNamespacedPath"],
+    perf_hooks: ["performance", "PerformanceObserver"],
+    process: ["env", "argv", "platform", "arch", "version", "versions", "stdout", "stderr", "stdin", "cwd", "chdir", "exit", "nextTick", "pid", "ppid"],
+    querystring: ["parse", "stringify", "escape", "unescape"],
+    readline: ["createInterface", "Interface"],
+    stream: ["Readable", "Writable", "Transform", "PassThrough", "Duplex", "pipeline", "finished", "promises"],
+    "stream/web": ["ReadableStream", "WritableStream", "TransformStream", "ByteLengthQueuingStrategy", "CountQueuingStrategy"],
+    tls: ["createServer", "connect", "createSecureContext", "TLSSocket", "Server", "checkServerIdentity", "rootCertificates", "DEFAULT_CIPHERS", "DEFAULT_MIN_VERSION", "DEFAULT_MAX_VERSION"],
+    tty: ["isatty", "ReadStream", "WriteStream"],
+    url: ["URL", "URLSearchParams", "fileURLToPath", "pathToFileURL", "format", "parse", "resolve", "domainToASCII", "domainToUnicode"],
+    util: ["promisify", "inspect", "format", "deprecate", "callbackify", "TextDecoder", "TextEncoder", "types", "isDeepStrictEqual"],
+    vm: ["createContext", "runInContext", "runInNewContext", "runInThisContext", "Script"],
+    worker_threads: ["Worker", "isMainThread", "parentPort", "workerData", "threadId"],
+    zlib: ["gzip", "gunzip", "gzipSync", "gunzipSync", "deflate", "inflate", "deflateSync", "inflateSync", "createGzip", "createGunzip", "createDeflate", "createInflate", "constants", "brotliCompress", "brotliDecompress", "brotliCompressSync", "brotliDecompressSync"],
+    ws: ["WebSocket", "WebSocketServer", "Server", "createWebSocketStream"],
+  };
+  return {
+    name: "astrid-node-builtin-stub",
+    setup(build) {
+      build.onResolve({ filter: /^(node:)?[^./].*$/ }, (args) => {
+        const stripped = args.path.startsWith("node:")
+          ? args.path.slice(5)
+          : args.path;
+        if (Object.prototype.hasOwnProperty.call(namedExports, stripped)) {
+          return { path: stripped, namespace: "astrid-node-stub" };
+        }
+        return null;
+      });
+      build.onLoad(
+        { filter: /.*/, namespace: "astrid-node-stub" },
+        (args) => {
+          const names = namedExports[args.path] ?? [];
+          const exportLines = names
+            .map((n) => `export const ${n} = makeStub(${JSON.stringify(n)});`)
+            .join("\n");
+          return {
+            loader: "js",
+            contents: `
+const importPath = ${JSON.stringify(args.path)};
+const throwUnavailable = (member) => {
+  throw new Error(
+    "Capsule reached node-builtin stub: " + importPath +
+    (member ? "." + member : "") +
+    " is not available on wasm32. The capsule must avoid this code path " +
+    "or replace the import with a web-equivalent (e.g. globalThis.crypto " +
+    "for WebCrypto, astrid_sdk net for sockets)."
+  );
+};
+const makeStub = (member) => new Proxy(function () {}, {
+  get(_target, prop) {
+    if (typeof prop === "symbol") return undefined;
+    return makeStub((member ? member + "." : "") + String(prop));
+  },
+  apply() { throwUnavailable(member); },
+  construct() { throwUnavailable(member); },
+});
+${exportLines}
+export default makeStub("");
+`,
+          };
+        },
+      );
+    },
+  };
+}
+
+async function bundle(entryPath, projectDir) {
+  const genDir = dirname(entryPath);
+  const bundlePath = join(genDir, "_entry.mjs");
+  await esbuild.build({
+    entryPoints: [entryPath],
+    bundle: true,
+    format: "esm",
+    // Browser platform so esbuild honors the `browser` field in package.json
+    // (node-forge maps `crypto`/`buffer`/`process` to empty modules; libp2p
+    // maps its node:crypto-using files to .browser.js variants that use
+    // WebCrypto). StarlingMonkey provides WebCrypto via globalThis.crypto
+    // but does NOT provide node:crypto/node:events/etc., so the Node
+    // variants of these packages would fail at bundle time. The capsule
+    // runtime surface is web-like, not Node-like, on every axis that
+    // matters for bundling.
+    platform: "browser",
+    target: "es2022",
+    outfile: bundlePath,
+    // Mark WIT module specifiers as external so esbuild doesn't try to
+    // resolve them — ComponentizeJS owns those imports. Post per-domain WIT
+    // split, the specifiers are `astrid:<domain>/host@1.0.0` and
+    // `astrid:io/<iface>@1.0.0`; the bare `astrid:*` glob covers both.
+    external: ["astrid:*"],
+    // Working dir resolution: esbuild needs to look in the project's
+    // node_modules to find @unicity-astrid/sdk via the workspace symlink.
+    absWorkingDir: projectDir,
+    // Conditional exports: prefer ESM, then browser-conditional entries
+    // (Sphere SDK's `./impl/browser` etc.). `node` is intentionally
+    // omitted — the capsule runtime can't satisfy node:* builtins.
+    conditions: ["import", "module", "browser"],
+    // Stub Node builtins + Node-adjacent packages that may leak in from
+    // dual-target dependencies (libp2p, sphere-sdk, etc.). See plugin doc.
+    plugins: [nodeBuiltinStubPlugin()],
+    // Don't minify — we want readable error messages during development.
+    // Componentize will be the one stripping for size.
+    minify: false,
+    sourcemap: false,
+  });
+  return bundlePath;
+}
+
+function resolveWitPath() {
+  // Read straight from the canonical `unicity-astrid/wit` submodule. The
+  // kernel side (cargo-published `astrid-sys` crate) keeps an in-tree copy
+  // because `cargo package` only bundles files inside the crate dir; the
+  // JS SDK has no such constraint, so we consume the submodule directly
+  // and skip the drift surface entirely. Sanity-check that the per-domain
+  // split landed — `ipc@1.0.0.wit` is the canary file that appears on the
+  // new layout but never the old.
+  if (!existsSync(join(CANONICAL_WIT_DIR, "ipc@1.0.0.wit"))) {
+    die(
+      `canonical host WIT missing or pre-split at ${CANONICAL_WIT_DIR}. ` +
+        `Expected per-domain layout from unicity-astrid/wit; run 'git submodule update --init --recursive' from the sdk-js repo root.`,
+    );
+  }
+  return CANONICAL_WIT_DIR;
+}
+
+/**
+ * Stage the canonical host WIT files into a synthesized deps tree that
+ * componentize-js can resolve, then emit a single `astrid-sdk:capsule` world
+ * that imports every per-domain host package and includes every guest export
+ * world. Mirrors the Rust SDK's `astrid-sys` synthetic world (see
+ * `sdk-rust/astrid-sys/src/lib.rs`) so the two SDKs target the same world.
+ *
+ * Layout produced under `<projectDir>/gen/wit/`:
+ *
+ *   capsule.wit                    (the synthetic world)
+ *   deps/astrid-io/io@1.0.0.wit
+ *   deps/astrid-fs/fs@1.0.0.wit
+ *   deps/astrid-ipc/ipc@1.0.0.wit
+ *   ... (one dir per per-domain package)
+ *   deps/astrid-guest/guest@1.0.0.wit
+ *
+ * The deps/ dir is the WIT convention componentize-js / wit-bindgen uses to
+ * find external packages.
+ */
+async function stageCapsuleWit(projectDir) {
+  const witDir = join(projectDir, "gen", "wit");
+  const depsDir = join(witDir, "deps");
+  await rm(witDir, { recursive: true, force: true });
+  await mkdir(depsDir, { recursive: true });
+
+  // Map of <wit-file-name> → <deps subdir name> (the bare package name
+  // without the version is the conventional subdir).
+  const hostFiles = await readdir(CANONICAL_WIT_DIR);
+  const stagedPkgs = [];
+  for (const fname of hostFiles) {
+    if (!fname.endsWith(".wit")) continue;
+    // `ipc@1.0.0.wit` → bare package "ipc"
+    const bare = fname.replace(/@.*$/, "");
+    const subdir = join(depsDir, `astrid-${bare}`);
+    await mkdir(subdir, { recursive: true });
+    await copyFile(join(CANONICAL_WIT_DIR, fname), join(subdir, fname));
+    stagedPkgs.push(bare);
+  }
+
+  const world = `// Auto-generated by @unicity-astrid/build. Do not edit by hand.
+//
+// Synthetic capsule world combining every frozen per-domain host import
+// plus every guest export world. Mirrors the Rust SDK's astrid-sys
+// synthetic world so capsules built with either SDK target the same world.
+
+package astrid-sdk:capsule;
+
+world capsule {
+    import astrid:io/error@1.0.0;
+    import astrid:io/poll@1.0.0;
+    import astrid:io/streams@1.0.0;
+
+    import astrid:fs/host@1.0.0;
+    import astrid:ipc/host@1.0.0;
+    import astrid:kv/host@1.0.0;
+    import astrid:net/host@1.0.0;
+    import astrid:http/host@1.0.0;
+    import astrid:sys/host@1.0.0;
+    import astrid:process/host@1.0.0;
+    import astrid:uplink/host@1.0.0;
+    import astrid:elicit/host@1.0.0;
+    import astrid:approval/host@1.0.0;
+    import astrid:identity/host@1.0.0;
+
+    include astrid:guest/interceptor@1.0.0;
+    include astrid:guest/background@1.0.0;
+    include astrid:guest/installable@1.0.0;
+    include astrid:guest/upgradable@1.0.0;
+}
+`;
+  await writeFile(join(witDir, "capsule.wit"), world);
+  return witDir;
+}
+
+async function runComponentize(entryPath, outPath, projectDir) {
+  // Sanity-check the canonical host WIT exists before staging.
+  resolveWitPath();
+  const witPath = await stageCapsuleWit(projectDir);
+  const t0 = performance.now();
+  const { component, imports } = await componentize({
+    sourcePath: entryPath,
+    witPath,
+    worldName: "capsule",
+    // Phase 0 finding: ALL features must be disabled to avoid pulling in
+    // WASI 0.2 imports the Astrid kernel doesn't satisfy.
+    disableFeatures: ["stdio", "random", "clocks", "http", "fetch-event"],
+  });
+  const elapsedMs = performance.now() - t0;
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, component);
+  const info = await stat(outPath);
+  return {
+    bytes: info.size,
+    componentizeSec: (elapsedMs / 1000).toFixed(2),
+    importCount: imports.length,
+  };
+}
+
+async function main() {
+  const { projectDir, out } = parseArgs(process.argv.slice(2));
+  if (!existsSync(projectDir)) die(`project directory does not exist: ${projectDir}`);
+
+  const { name } = await resolveProjectMetadata(projectDir);
+  const outPath = out ?? join(projectDir, "target", `${name}.wasm`);
+
+  // WIT events codegen runs BEFORE tsc so the generated .d.ts files are
+  // visible during type-checking. Idempotent: if there's no wit/ dir,
+  // returns { files: 0, types: 0 } and skips the work.
+  const witResult = await codegenWitEvents(projectDir);
+  if (witResult.files > 0) {
+    console.log(
+      `astrid-js-build: wit-events emitted ${witResult.types} type(s) from ${witResult.files} file(s)`,
+    );
+  }
+
+  const outDir = compileTypeScript(projectDir);
+  const userEntry = resolveEntry(projectDir, outDir);
+  console.log(`astrid-js-build: user entry = ${userEntry}`);
+  const entrySrcPath = await emitEntry(projectDir, userEntry);
+  console.log(`astrid-js-build: generated entry = ${entrySrcPath}`);
+  const bundledPath = await bundle(entrySrcPath, projectDir);
+  console.log(`astrid-js-build: bundled = ${bundledPath}`);
+  console.log("astrid-js-build: running componentize-js...");
+  const result = await runComponentize(bundledPath, outPath, projectDir);
+  console.log(
+    `astrid-js-build: wrote ${outPath} (${(result.bytes / 1024 / 1024).toFixed(2)} MB, ${result.componentizeSec}s, ${result.importCount} host imports)`,
+  );
+  // The kernel-side Rust caller can parse this JSON for the binary path
+  // without scraping logs.
+  console.log(
+    `astrid-js-build-result: ${JSON.stringify({ wasmPath: outPath, bytes: result.bytes })}`,
+  );
+}
+
+function posixRelative(fromDir, toFile) {
+  let rel = relative(fromDir, toFile);
+  if (sep !== "/") rel = rel.split(sep).join("/");
+  if (!rel.startsWith(".")) rel = "./" + rel;
+  return rel;
+}
+
+main().catch((err) => {
+  console.error("astrid-js-build: FAILED");
+  console.error(err?.stack ?? err);
+  process.exit(1);
+});

package/src/wit-codegen.mjs

@@ -0,0 +1,209 @@
+/**
+ * Walks a project's wit/ directory, parses each .wit file, and emits
+ * `gen/<file>.d.ts` files with TypeScript types for every named record,
+ * enum, variant, and flags.
+ *
+ * Mirror of `astrid_sdk_macros::wit_events::generate` (Rust). Naming:
+ *   - kebab-case names → PascalCase in TS (matching the Rust output's
+ *     PascalCase struct names).
+ *   - kebab-case field names → snake_case (matching Rust's
+ *     `#[serde(rename_all = "snake_case")]` on generated structs, so the
+ *     wire format is identical regardless of which SDK produced it).
+ *   - option<T> → T | undefined (with optional `?:` field syntax).
+ *   - list<T> → T[].
+ *   - tuple<T,U,...> → [T, U, ...].
+ *   - variants → discriminated unions with `tag` + optional `value`.
+ *   - flags → string-array of variant names.
+ */
+
+import { parseWit } from "./wit-parser.mjs";
+import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, basename, extname } from "node:path";
+
+export async function codegenWitEvents(projectDir) {
+  const witDir = join(projectDir, "wit");
+  let entries;
+  try {
+    entries = await readdir(witDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return { files: 0, types: 0 };
+    throw err;
+  }
+
+  const witFiles = entries
+    .filter((e) => e.isFile() && extname(e.name) === ".wit")
+    .map((e) => join(witDir, e.name));
+
+  if (witFiles.length === 0) return { files: 0, types: 0 };
+
+  const genDir = join(projectDir, "gen");
+  await mkdir(genDir, { recursive: true });
+
+  let totalTypes = 0;
+  for (const witPath of witFiles) {
+    const source = await readFile(witPath, "utf8");
+    const ast = parseWit(source, witPath);
+    const ts = emitTs(ast);
+    const baseName = basename(witPath, ".wit");
+    const outPath = join(genDir, `${baseName}.d.ts`);
+    await writeFile(outPath, ts);
+    totalTypes += ast.interfaces.reduce((sum, iface) => sum + iface.types.length, 0);
+  }
+
+  return { files: witFiles.length, types: totalTypes };
+}
+
+function emitTs(ast) {
+  const lines = [
+    "// Auto-generated by @unicity-astrid/build from a WIT file. Do not edit by hand.",
+    "// Mirror of `astrid_sdk_macros::wit_events!` output.",
+    "",
+  ];
+
+  // Per-interface namespacing prevents collisions across the canonical
+  // interface set — agent / approval / elicit all define `record
+  // response`, and all three must be addressable. Build an owner index
+  // so cross-interface references can fully qualify
+  // (e.g. `types.Message` inside the `llm` namespace).
+  const typeOwner = new Map();
+  for (const iface of ast.interfaces) {
+    for (const t of iface.types) {
+      typeOwner.set(t.name, kebabToSnake(iface.name));
+    }
+  }
+
+  for (const iface of ast.interfaces) {
+    const ns = kebabToSnake(iface.name);
+    lines.push(`/** Types generated from the \`${iface.name}\` WIT interface. */`);
+    lines.push(`export namespace ${ns} {`);
+    for (const t of iface.types) {
+      if (t.doc) emitDoc(lines, t.doc, "  ");
+      if (t.kind === "record") emitRecord(lines, t, typeOwner, ns);
+      else if (t.kind === "enum") emitEnum(lines, t);
+      else if (t.kind === "variant") emitVariant(lines, t, typeOwner, ns);
+      else if (t.kind === "flags") emitFlags(lines, t);
+      lines.push("");
+    }
+    lines.push(`}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function emitRecord(lines, t, typeOwner, currentNs) {
+  lines.push(`  export interface ${kebabToPascal(t.name)} {`);
+  for (const f of t.fields) {
+    if (f.doc) emitDoc(lines, f.doc, "    ");
+    const fieldName = kebabToSnake(f.name);
+    const isOption = f.type.kind === "option";
+    const renderedType = renderType(isOption ? f.type.inner : f.type, typeOwner, currentNs);
+    if (isOption) {
+      lines.push(`    ${fieldName}?: ${renderedType};`);
+    } else {
+      lines.push(`    ${fieldName}: ${renderedType};`);
+    }
+  }
+  lines.push(`  }`);
+}
+
+function emitEnum(lines, t) {
+  const variants = t.cases.map((c) => JSON.stringify(kebabToSnake(c.name))).join(" | ");
+  lines.push(`  export type ${kebabToPascal(t.name)} = ${variants};`);
+}
+
+function emitVariant(lines, t, typeOwner, currentNs) {
+  // Mirror serde(tag = "tag", content = "value") — see wit_events.rs
+  // line 113. Wire format: `{ tag: "case-name", value?: T }`.
+  const cases = t.cases.map((c) => {
+    const tag = kebabToSnake(c.name);
+    if (c.type === undefined) return `{ tag: ${JSON.stringify(tag)} }`;
+    return `{ tag: ${JSON.stringify(tag)}; value: ${renderType(c.type, typeOwner, currentNs)} }`;
+  });
+  lines.push(`  export type ${kebabToPascal(t.name)} =`);
+  for (let i = 0; i < cases.length; i++) {
+    lines.push(`    | ${cases[i]}${i === cases.length - 1 ? ";" : ""}`);
+  }
+}
+
+function emitFlags(lines, t) {
+  // Mirror the Rust output: `type X = Vec<XFlag>;` becomes
+  // `type X = XFlag[]; type XFlag = "case" | ...`.
+  const flagName = kebabToPascal(t.name) + "Flag";
+  const flagUnion = t.cases.map((c) => JSON.stringify(kebabToSnake(c.name))).join(" | ");
+  lines.push(`  export type ${flagName} = ${flagUnion};`);
+  lines.push(`  export type ${kebabToPascal(t.name)} = ${flagName}[];`);
+}
+
+function renderType(ty, typeOwner, currentNs) {
+  switch (ty.kind) {
+    case "builtin":
+      return renderBuiltin(ty.name);
+    case "option":
+      return `${renderType(ty.inner, typeOwner, currentNs)} | undefined`;
+    case "list":
+      return `${renderType(ty.inner, typeOwner, currentNs)}[]`;
+    case "tuple":
+      return `[${ty.elems.map((e) => renderType(e, typeOwner, currentNs)).join(", ")}]`;
+    case "named": {
+      const pascal = kebabToPascal(ty.name);
+      // If the type lives in another interface, fully qualify so the
+      // reference resolves under the parent module instead of looking
+      // for it inside the current namespace.
+      const owner = typeOwner && typeOwner.get(ty.name);
+      if (owner && owner !== currentNs) return `${owner}.${pascal}`;
+      return pascal;
+    }
+    case "unknown":
+      return "unknown";
+    default:
+      return "unknown";
+  }
+}
+
+function renderBuiltin(name) {
+  switch (name) {
+    case "bool":
+      return "boolean";
+    case "string":
+    case "char":
+      return "string";
+    case "u8":
+    case "u16":
+    case "u32":
+    case "s8":
+    case "s16":
+    case "s32":
+    case "f32":
+    case "f64":
+      return "number";
+    case "u64":
+    case "s64":
+      // 64-bit integers cross the WIT boundary as bigint in jco bindings.
+      return "bigint";
+    default:
+      return "unknown";
+  }
+}
+
+function kebabToPascal(s) {
+  return s
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+function kebabToSnake(s) {
+  return s.replace(/-/g, "_");
+}
+
+function emitDoc(lines, doc, indent = "") {
+  const docLines = doc.split("\n");
+  if (docLines.length === 1) {
+    lines.push(`${indent}/** ${docLines[0]} */`);
+    return;
+  }
+  lines.push(`${indent}/**`);
+  for (const dl of docLines) lines.push(`${indent} * ${dl}`);
+  lines.push(`${indent} */`);
+}

package/src/wit-parser.mjs

@@ -0,0 +1,382 @@
+/**
+ * Minimal WIT parser sufficient for the wit_events codegen step.
+ *
+ * Mirrors the subset the Rust `astrid_sdk_macros::wit_events!` macro
+ * handles: records, enums, variants, flags. Skips resource types,
+ * functions, and use/import statements (codegen doesn't emit code for
+ * those — they're for the WIT-to-binding layer ComponentizeJS owns).
+ *
+ * Input: WIT file content (string).
+ * Output: an AST suitable for the codegen step to walk.
+ */
+
+const BUILTIN_TYPES = new Set([
+  "bool",
+  "u8", "u16", "u32", "u64",
+  "s8", "s16", "s32", "s64",
+  "f32", "f64",
+  "char",
+  "string",
+]);
+
+/** Parse WIT source. Returns `{ pkg, interfaces }`. */
+export function parseWit(source, filename = "<input>") {
+  const tokens = tokenize(source);
+  const parser = new Parser(tokens, filename);
+  return parser.parseFile();
+}
+
+function tokenize(source) {
+  const tokens = [];
+  let i = 0;
+  let line = 1;
+  let pendingDoc = "";
+
+  while (i < source.length) {
+    const ch = source[i];
+
+    if (ch === "\n") {
+      line++;
+      i++;
+      continue;
+    }
+    if (ch === " " || ch === "\t" || ch === "\r") {
+      i++;
+      continue;
+    }
+
+    // Doc comment: /// ...
+    if (ch === "/" && source[i + 1] === "/" && source[i + 2] === "/") {
+      let end = source.indexOf("\n", i);
+      if (end === -1) end = source.length;
+      const line_doc = source.slice(i + 3, end).replace(/^ /, "");
+      pendingDoc = pendingDoc === "" ? line_doc : pendingDoc + "\n" + line_doc;
+      i = end;
+      continue;
+    }
+    // Block comment: /* ... */
+    if (ch === "/" && source[i + 1] === "*") {
+      const end = source.indexOf("*/", i + 2);
+      if (end === -1) throw new Error(`Unterminated block comment at line ${line}`);
+      const block = source.slice(i + 2, end);
+      line += (block.match(/\n/g) ?? []).length;
+      i = end + 2;
+      continue;
+    }
+    // Line comment: // ... (non-doc)
+    if (ch === "/" && source[i + 1] === "/") {
+      let end = source.indexOf("\n", i);
+      if (end === -1) end = source.length;
+      i = end;
+      continue;
+    }
+
+    // Punctuation
+    const single = "{}<>(),;:.@/=%";
+    if (single.indexOf(ch) >= 0) {
+      tokens.push({ kind: "punct", value: ch, line, doc: "" });
+      i++;
+      continue;
+    }
+
+    // Quoted identifier (escape with %): %type, %if, etc.
+    if (ch === "%") {
+      let j = i + 1;
+      while (j < source.length && /[A-Za-z0-9_-]/.test(source[j])) j++;
+      const id = source.slice(i + 1, j);
+      if (id.length === 0) throw new Error(`Empty %-escaped identifier at line ${line}`);
+      tokens.push({ kind: "ident", value: id, line, doc: pendingDoc });
+      pendingDoc = "";
+      i = j;
+      continue;
+    }
+
+    // Identifier / keyword
+    if (/[A-Za-z_]/.test(ch)) {
+      let j = i;
+      while (j < source.length && /[A-Za-z0-9_-]/.test(source[j])) j++;
+      const id = source.slice(i, j);
+      tokens.push({ kind: "ident", value: id, line, doc: pendingDoc });
+      pendingDoc = "";
+      i = j;
+      continue;
+    }
+
+    // Number (version segments)
+    if (/[0-9]/.test(ch)) {
+      let j = i;
+      while (j < source.length && /[0-9]/.test(source[j])) j++;
+      tokens.push({ kind: "num", value: source.slice(i, j), line, doc: "" });
+      i = j;
+      continue;
+    }
+
+    throw new Error(`Unexpected character '${ch}' at line ${line}`);
+  }
+
+  tokens.push({ kind: "eof", value: "", line, doc: "" });
+  return tokens;
+}
+
+class Parser {
+  constructor(tokens, filename) {
+    this.tokens = tokens;
+    this.filename = filename;
+    this.pos = 0;
+  }
+
+  peek(offset = 0) {
+    return this.tokens[this.pos + offset];
+  }
+
+  eat() {
+    return this.tokens[this.pos++];
+  }
+
+  expect(kind, value) {
+    const t = this.eat();
+    if (t.kind !== kind || (value !== undefined && t.value !== value)) {
+      throw new Error(
+        `${this.filename}:${t.line}: expected ${kind}${value !== undefined ? ` '${value}'` : ""} got ${t.kind} '${t.value}'`,
+      );
+    }
+    return t;
+  }
+
+  match(kind, value) {
+    const t = this.peek();
+    return t.kind === kind && (value === undefined || t.value === value);
+  }
+
+  parseFile() {
+    let pkg;
+    const interfaces = [];
+
+    while (!this.match("eof")) {
+      if (this.match("ident", "package")) {
+        pkg = this.parsePackage();
+      } else if (this.match("ident", "interface")) {
+        interfaces.push(this.parseInterface());
+      } else if (this.match("ident", "world")) {
+        // Skip world declarations — we only care about types.
+        this.skipBraced();
+      } else {
+        const t = this.peek();
+        throw new Error(`${this.filename}:${t.line}: unexpected token '${t.value}' at file scope`);
+      }
+    }
+
+    return { pkg, interfaces };
+  }
+
+  parsePackage() {
+    this.expect("ident", "package");
+    const ns = this.expect("ident").value;
+    this.expect("punct", ":");
+    const name = this.expect("ident").value;
+    let version;
+    if (this.match("punct", "@")) {
+      this.eat();
+      version = this.parseVersion();
+    }
+    this.expect("punct", ";");
+    return { ns, name, version };
+  }
+
+  parseVersion() {
+    const parts = [];
+    parts.push(this.expect("num").value);
+    while (this.match("punct", ".")) {
+      this.eat();
+      parts.push(this.expect("num").value);
+    }
+    return parts.join(".");
+  }
+
+  parseInterface() {
+    this.expect("ident", "interface");
+    const name = this.expect("ident").value;
+    this.expect("punct", "{");
+
+    const types = [];
+    while (!this.match("punct", "}")) {
+      const doc = this.peek().doc;
+      if (this.match("ident", "use")) {
+        this.skipStatement();
+        continue;
+      }
+      if (this.match("ident", "record")) {
+        types.push(this.parseRecord(doc));
+        continue;
+      }
+      if (this.match("ident", "enum")) {
+        types.push(this.parseEnum(doc));
+        continue;
+      }
+      if (this.match("ident", "variant")) {
+        types.push(this.parseVariant(doc));
+        continue;
+      }
+      if (this.match("ident", "flags")) {
+        types.push(this.parseFlags(doc));
+        continue;
+      }
+      if (this.match("ident", "type")) {
+        // type alias — record but skip codegen
+        this.skipStatement();
+        continue;
+      }
+      // Function declarations: name: func(...) -> ...
+      // We only care about types here; skip the rest of the line.
+      this.skipStatement();
+    }
+    this.expect("punct", "}");
+    return { name, types };
+  }
+
+  parseRecord(doc) {
+    this.expect("ident", "record");
+    const name = this.expect("ident").value;
+    this.expect("punct", "{");
+    const fields = [];
+    while (!this.match("punct", "}")) {
+      const fieldDoc = this.peek().doc;
+      const fieldName = this.expect("ident").value;
+      this.expect("punct", ":");
+      const ty = this.parseType();
+      fields.push({ name: fieldName, type: ty, doc: fieldDoc });
+      if (this.match("punct", ",")) this.eat();
+    }
+    this.expect("punct", "}");
+    return { kind: "record", name, fields, doc };
+  }
+
+  parseEnum(doc) {
+    this.expect("ident", "enum");
+    const name = this.expect("ident").value;
+    this.expect("punct", "{");
+    const cases = [];
+    while (!this.match("punct", "}")) {
+      const caseDoc = this.peek().doc;
+      const caseName = this.expect("ident").value;
+      cases.push({ name: caseName, doc: caseDoc });
+      if (this.match("punct", ",")) this.eat();
+    }
+    this.expect("punct", "}");
+    return { kind: "enum", name, cases, doc };
+  }
+
+  parseVariant(doc) {
+    this.expect("ident", "variant");
+    const name = this.expect("ident").value;
+    this.expect("punct", "{");
+    const cases = [];
+    while (!this.match("punct", "}")) {
+      const caseDoc = this.peek().doc;
+      const caseName = this.expect("ident").value;
+      let ty;
+      if (this.match("punct", "(")) {
+        this.eat();
+        ty = this.parseType();
+        this.expect("punct", ")");
+      }
+      cases.push({ name: caseName, type: ty, doc: caseDoc });
+      if (this.match("punct", ",")) this.eat();
+    }
+    this.expect("punct", "}");
+    return { kind: "variant", name, cases, doc };
+  }
+
+  parseFlags(doc) {
+    this.expect("ident", "flags");
+    const name = this.expect("ident").value;
+    this.expect("punct", "{");
+    const cases = [];
+    while (!this.match("punct", "}")) {
+      const caseDoc = this.peek().doc;
+      const caseName = this.expect("ident").value;
+      cases.push({ name: caseName, doc: caseDoc });
+      if (this.match("punct", ",")) this.eat();
+    }
+    this.expect("punct", "}");
+    return { kind: "flags", name, cases, doc };
+  }
+
+  parseType() {
+    const t = this.eat();
+    if (t.kind !== "ident") {
+      throw new Error(`${this.filename}:${t.line}: expected type, got ${t.kind} '${t.value}'`);
+    }
+    const name = t.value;
+    if (BUILTIN_TYPES.has(name)) {
+      return { kind: "builtin", name };
+    }
+    if (name === "option") {
+      this.expect("punct", "<");
+      const inner = this.parseType();
+      this.expect("punct", ">");
+      return { kind: "option", inner };
+    }
+    if (name === "list") {
+      this.expect("punct", "<");
+      const inner = this.parseType();
+      this.expect("punct", ">");
+      return { kind: "list", inner };
+    }
+    if (name === "tuple") {
+      this.expect("punct", "<");
+      const elems = [];
+      elems.push(this.parseType());
+      while (this.match("punct", ",")) {
+        this.eat();
+        elems.push(this.parseType());
+      }
+      this.expect("punct", ">");
+      return { kind: "tuple", elems };
+    }
+    if (name === "result") {
+      // result<T, E> or result<_, E> or result. Skip for now — events
+      // shouldn't have result fields. If we encounter one, decay to `any`.
+      if (this.match("punct", "<")) {
+        this.skipBraced("<", ">");
+      }
+      return { kind: "unknown" };
+    }
+    // Named reference to another record/enum/variant.
+    return { kind: "named", name };
+  }
+
+  skipStatement() {
+    let depth = 0;
+    while (!this.match("eof")) {
+      const t = this.eat();
+      if (t.kind === "punct") {
+        if (t.value === "(" || t.value === "<" || t.value === "{") depth++;
+        else if (t.value === ")" || t.value === ">" || t.value === "}") {
+          if (depth === 0) {
+            // A bare closer ends our scan, but we shouldn't consume it
+            // unless we opened it. Put it back.
+            this.pos--;
+            return;
+          }
+          depth--;
+        } else if (t.value === ";" && depth === 0) {
+          return;
+        }
+      }
+    }
+  }
+
+  skipBraced(open = "{", close = "}") {
+    // If the next token is the opener, consume it.
+    if (this.match("punct", open)) this.eat();
+    let depth = 1;
+    while (depth > 0 && !this.match("eof")) {
+      const t = this.eat();
+      if (t.kind === "punct") {
+        if (t.value === open) depth++;
+        else if (t.value === close) depth--;
+      }
+    }
+  }
+}