xbintsc 0.3.81 → 0.5.6

package/doc/ai/troubleshooting.md

@@ -22,8 +22,12 @@ D:\...\build\app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but e
 
 The compiler emits LLVM IR that relies on opaque pointers; typed pointers were
 removed in LLVM 16 ([LLVM release notes](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)).
-Confirm with `clang --version`; if the machine has an old system clang, install a
-newer LLVM and point xbintsc at it:
+`xbintsc build`/`run` check the version up front and stop with "reports clang
+15.0.2, but xbintsc requires clang 16 or newer", and `xbintsc doctor` prints
+`status : ok` or `status : too old` (exiting non-zero in the latter case). The
+search prefers a supported clang — including the LLVM bundled with Visual Studio
+on Windows — so an old `/usr/bin/clang` is skipped when a newer one is installed.
+To choose one explicitly:
 
 ```bash
 export xbintsc_CLANG=/usr/lib/llvm-18/bin/clang     # PowerShell: $env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
@@ -118,6 +122,39 @@ described in [../gui.md](../gui.md).
 Windows, embedding a PE icon needs `llvm-rc` or `windres`; `doctor` reports which
 one was found, and a missing one is only fatal when an icon was requested.
 
+## Reading a stack trace
+
+`Error.stack` is captured by codegen, not from the C runtime's native frames:
+every non-generator function pushes `{name, file, line}` on entry and pops it
+before returning. Frames look like
+
+```
+Error: boom
+    at inner (app.ts:12)
+    at module (app.ts:3)
+```
+
+Lines are function declaration lines, except that the innermost frame is moved
+to the `new Error(...)` line; there are no column numbers. Generator bodies are
+not tracked because they switch stacks. A fatal native signal prints
+`xbintsc: fatal signal …` followed by the same frames, so a crash without a
+debugger still shows which JavaScript functions were running.
+
+## Debugging with gdb / lldb / WinDbg
+
+`xbintsc build app.ts --debug` emits LLVM debug metadata and passes `-g
+-fno-omit-frame-pointer` to clang, so the object carries DWARF (Linux/macOS) or
+CodeView (Windows) line tables. Function symbols keep their source names
+(`xt_fn_3_add`) and every statement has a line location:
+
+```bash
+xbintsc build app.ts --debug
+gdb ./build/app          # or: lldb ./build/app, or open the .exe in WinDbg
+```
+
+The binary is larger and is cached separately from a normal build (the debug
+flag is part of the cache key). `Error.stack` works without `--debug`.
+
 ## Build behaviour that looks wrong but is not
 
 ### The build printed `(cached)` and did nothing
@@ -144,9 +181,10 @@ directly (`./build/app`) to see the program's own output.
 
 ### Program output appears in an unexpected order
 
-`async`/`await` is a synchronous microtask model and the event loop only runs
-after the program body. Timer and socket callbacks therefore fire late; see
-[language-support.md](./language-support.md).
+`async`/`await` suspends only on a **pending** promise; awaiting an already
+settled value continues synchronously instead of queueing a microtask the way
+Node does. The event loop starts after the program body, so timer and socket
+callbacks still fire after it; see [language-support.md](./language-support.md).
 
 ## Where to look in the code
 

package/doc/ai/zh-CN/cli.md

@@ -33,6 +33,8 @@
     --app-id <id>     macOS bundle 标识（如 com.example.demo）
     --force           忽略增量缓存
     --verbose         打印进度信息
+    --time            打印各构建阶段耗时
+    --debug           生成调试信息（DWARF/CodeView）并保留帧指针
 ```
 
 少数容易踩的解析细节：

package/doc/ai/zh-CN/contributing.md

@@ -35,6 +35,7 @@ git config core.hooksPath .githooks
 | `npm run test:watch` | vitest 监听模式 |
 | `npm run coverage` | TypeScript 编译器（`src/`）的 V8 覆盖率 |
 | `npm run coverage:runtime` | C 运行时（`runtime/`）的 LLVM 覆盖率 |
+| `npm run bench` | 构建并计时固定基准套件（可与 Node 对比） |
 
 单元测试在 `tests/` 下按模块一个目录（`lexer`、`parser`、`binder`、`codegen`、
 `driver`、`extensions`、`cli`、`e2e`），与源码树镜像对应。边界用例放在它覆盖的模块
@@ -66,11 +67,11 @@ gen2 --emit--> gen3.ll      # 必须等于 ref.ll
 必须逐字节确定——包括迭代顺序、生成的符号名与编号。绝不要把不确定性（未受控的
 `Map`/`Set` 迭代顺序、时间戳、依赖文件系统顺序的东西）引入代码生成。
 
-第二个推论是字符串模型：编译器自身源码文本在各代中必须含义一致。编译后的字符串是
-UTF-8 字节，所以自举后的 `readFileSync`（`--ext node`）交给扫描器的是文件字节，而
-Node 交给它的是同一个文件已解码后的文本——读取源码文件一律走 `decodeUtf8`
-（[src/diagnostics/utf8.ts](../../../src/diagnostics/utf8.ts)），不要假设一个码元就是
-一个字节或一个字符。弄错的表现是：`gen2.ll` 里非 ASCII 字面量（比如提示语里的 `—`）
+第二个推论是字符串模型：编译器自身源码文本在各代中必须含义一致。编译后的字符串以 UTF-8
+存储，但索引按 UTF-16 码元进行，所以自举后的 `readFileSync`（`--ext node`）交给扫描器的是
+字节串（一个码元一个字节，全部 `<= 0xFF`），而 Node 交给它的是同一个文件已解码后的文本——
+读取源码文件一律走 `decodeUtf8`（[src/diagnostics/utf8.ts](../../../src/diagnostics/utf8.ts)），
+不要假设一个码元就是一个字节或一个字符。弄错的表现是：`gen2.ll` 里非 ASCII 字面量（比如提示语里的 `—`）
 被重新编码，这也正是这里逐字节比较 IR 而不是逐行比较的原因。
 
 本地验证：
@@ -90,8 +91,11 @@ diff scratch/ref.ll scratch/gen2.ll
 - 每个值都是一个 64 位字：double 不装箱，其余都是带标签指针（16 位标签 + 48 位载荷）。
   该表示只定义一次：[../../../src/codegen/values.ts](../../../src/codegen/values.ts) 与
   [../../../runtime/rt.h](../../../runtime/rt.h)；要改就一起改，否则别动。
-- 别扭的 JS 语义（`+` 强转、关系比较、属性访问、打印）委托给 `@xt_*` 运行时调用，而
-  不是内联。
+- 别扭的 JS 语义（`+` 强转、关系比较、属性访问、打印）委托给 `@xt_*` 运行时调用。
+  数值算术与比较是例外：codegen 内联双 double 快路径
+  （`src/codegen/generator/numeric.ts`），其余情况调用运行时。
+- 字符串字面量会被驻留：每个不同字面量只在 `main` 中创建一次，存入 GC 根全局，
+  每次使用只做一次 load；属性名因此不再逐次分配。
 - GC 是非移动标记清扫：新堆对象走 `xt_alloc`；值存活期间必须能从显式根槽、已注册的
   根提供者（事件循环、微任务队列）或 C 栈保守扫描到达。只存在于未被扫描的 C 局部
   变量里的值就是 bug。

package/doc/ai/zh-CN/extensions.md

@@ -53,7 +53,8 @@ xbintsc run app.ts --ext node
 [../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md)。
 
 在 `net`/`http` 上搭东西之前，先记住运行时模型：事件循环在**程序主体之后**才运行，
-而 `async`/`await` 是同步微任务模型。见 [language-support.md](./language-support.md)。
+但 `async`/`await` 现在会在 pending Promise 上挂起，因此由套接字回调 settle 的 Promise
+可以被 await。见 [language-support.md](./language-support.md)。
 
 ### `gui` —— HTML/CSS 窗口
 

package/doc/ai/zh-CN/language-support.md

@@ -28,7 +28,7 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | `function`、箭头函数、默认参数/剩余参数 | ✅ | |
 | `namespace`/`module` 声明 | 🚫 | 解析 ✓，代码生成 ✗ |
 | `with`、`debugger` | 🚫 | 不支持 |
-| 顶层 `await` | 🚫 | 请包进 `async` 函数 |
+| 顶层 `await` | ⚠️ | 会在事件循环上阻塞直到 Promise settle（不会像 ES module 那样让出模块主体）；建议包进 `async` 函数 |
 
 ## 表达式与运算符
 
@@ -42,8 +42,8 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | 解构（绑定、参数、嵌套） | ✅ | 支持默认值与剩余 |
 | `delete`、`in`、`instanceof`、`typeof` | ✅ | |
 | 逗号运算符、`void` | ✅ | |
-| `new.target` | 🚫 | 未实现 |
-| `import.meta` | 🚫 | 能解析，但没有值 |
+| `new.target` | 🚫 | 能解析，但会给出明确的 `UnsupportedFeature` |
+| `import.meta` | ✅ | `url`、`dirname`、`filename`（由可执行文件路径解析） |
 | `super` | ⚠️ | 单层继承正确；继承深度 > 1 可能不准 |
 
 ## 函数、类与对象
@@ -68,10 +68,11 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 
 | 特性 | 状态 | 说明 |
 | --- | --- | --- |
-| `async`/`await`、`Promise`、`Promise.all` | ⚠️ | **同步微任务模型**——`await` 一个已敲定的 Promise 会同步继续 |
-| `setTimeout` 与回调 | ⚠️ | 事件循环在**程序主体之后**才运行，因此定时器里敲定的 Promise 无法被 await |
-| 套接字/服务端（`http`、`net`、`dgram`） | ⚠️ | 同一模型：回调在程序主体之后的循环里执行 |
-| 真正的异步事件循环、worker 线程 | 🚫 | 未实现 |
+| `async`/`await`、`Promise`、`Promise.all` | ✅ | 真实挂起：async 函数体运行在栈式协程上，等待**未 settle** 的 Promise 时暂停，settle 后恢复。等待已 settle 的值仍同步继续 |
+| `setTimeout` 与回调 | ✅ | 定时器运行在核心事件循环上；`await new Promise(r => setTimeout(r, ms))` 可用 |
+| 套接字/服务端（`http`、`net`、`dgram`） | ✅ | 回调在事件循环上执行，可以 settle 你正在 await 的 Promise（测试含 `net`/`http` 示例） |
+| `fs/promises` | ⚠️ | 可以 await，但每次调用仍先同步完成 I/O 再 settle，I/O 期间不会让出 |
+| `async` 生成器、worker 线程 | 🚫 | `async function*` 被拒绝；worker 是子进程 |
 
 ## 类型：解析后擦除
 
@@ -93,13 +94,14 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 已实现：`Math`、`JSON`、`Date`、`RegExp`、`Map`、`Set`、`WeakMap`/`WeakSet`、
 `Symbol`、`Error` 家族、`BigInt`、`Array`/`String`/`Number`/`Object` 方法、TypedArray、
 带捕获组的 `String.prototype.match`/`split`/`replace`、不可变数组方法
-（`toReversed`、`toSorted`、`toSpliced`、`with`）、全局 URI 函数。
+（`toReversed`、`toSorted`、`toSpliced`、`with`）、全局 URI 函数、
+一等公民内建构造器（`const A = Array; new A(...)`、`A.isArray`、`x instanceof A`）
+与 `Object.prototype`（`Object.getPrototypeOf({}) === Object.prototype`）。
 
 | 缺失或行为不同 | 状态 |
 | --- | --- |
 | `String.prototype.normalize`、`structuredClone` | 🚫 |
-| `Error.stack` 采集 | 🚫（不采集） |
-| `Object.getPrototypeOf({})` | ⚠️ 返回 `undefined`，而非 `Object.prototype` |
+| `Error.stack` 采集 | ⚠️ 函数级帧（名称/文件/行号），没有列号；生成器函数体不产生帧 |
 | 全局 RegExp `lastIndex` | ⚠️ `/g`、`/y` 下 `test`/`exec` 忽略它 |
 | 稀疏数组空洞、数组越界 | ⚠️ 不区分空洞；越界读得 `undefined` |
 
@@ -117,13 +119,14 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | `require()` / CommonJS | 🚫 | 被拒绝，并提示改用 `import` |
 | 循环依赖 | 🚫 | |
 | 实时绑定 | ⚠️ | 导入与命名空间成员都是快照 |
-| `import.meta`、`__dirname`、`__filename` | 🚫 | |
+| `__dirname`、`__filename` | 🚫 | 请使用 `import.meta.dirname` / `import.meta.filename` |
 
 ## 字符串、数字与内存
 
 | 项目 | 行为 |
 | --- | --- |
-| `String.prototype.length` | ⚠️ 按 **UTF-8 字节**计，不是 UTF-16 码元：`"é".length === 1`，`"😀".length === 4`；`codePointAt` 相应不同 |
+| `String.prototype.length` | ✅ UTF-16 码元（`"中文😀".length === 4`）；索引、`slice`、`indexOf`、`split`、`padStart`、`codePointAt` 使用同一模型。底层仍以 UTF-8 存储 |
+| 正则 Unicode 匹配 | ⚠️ 引擎按字节工作：字面量 `中` 仍能匹配，但 `.` 与字符类每次只消费一个字节，`\d`/`\w` 仍是 ASCII。匹配偏移（`match.index`、`search`、替换回调）按 UTF-16 码元报告 |
 | 数字格式化与强转 | ✅ 与 Node 一致（`toFixed`、`toPrecision`、十六/八/二进制解析） |
 | `BigInt` | ✅ 已实现 |
 | 垃圾回收 | ✅ 非移动标记清扫；显式根 + C 栈保守扫描；单线程、stop-the-world；无弱引用 |

package/doc/ai/zh-CN/troubleshooting.md

@@ -21,8 +21,11 @@ D:\...\build\app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but e
 
 编译器生成的 LLVM IR 依赖不透明指针（opaque pointers），而有类型指针在 LLVM 16
 中被移除（[LLVM 发布说明](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)）。
-用 `clang --version` 确认；如果机器上的系统 clang 太旧，装一个新版 LLVM 并让 xbintsc
-用它：
+`xbintsc build`/`run` 现在会先检查版本，直接停止并提示 "reports clang 15.0.2,
+but xbintsc requires clang 16 or newer"；`xbintsc doctor` 会打印
+`status : ok` 或 `status : too old`（后者以非零码退出）。搜索工具链时会优先选择受支持
+的 clang——包括 Windows 上 Visual Studio 自带的 LLVM——所以装了新版时旧的
+`/usr/bin/clang` 会被跳过。也可以显式指定：
 
 ```powershell
 $env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
@@ -110,6 +113,36 @@ clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——
 `llvm-rc` 或 `windres`；`doctor` 会报告找到了哪个，只有在确实请求了图标时缺失才是
 致命错误。
 
+## 怎么看堆栈
+
+`Error.stack` 由 codegen 采集，而不是依赖 C 运行时的原生帧：每个非生成器函数
+在入口压入 `{名称, 文件, 行号}`，返回前弹出。帧形如
+
+```
+Error: boom
+    at inner (app.ts:12)
+    at module (app.ts:3)
+```
+
+行号取函数声明行；最内层帧会更新为 `new Error(...)` 所在行。没有列号；生成器
+函数体因为会切换栈而不记录。原生致命信号会先打印 `xbintsc: fatal signal …`，
+再打印同一组帧，所以即使没有调试器也能看出崩溃时正在运行哪些 JS 函数。
+
+## 用 gdb / lldb / WinDbg 调试
+
+`xbintsc build app.ts --debug` 会生成 LLVM 调试元数据，并把 `-g
+-fno-omit-frame-pointer` 传给 clang，因此目标文件带有 DWARF（Linux/macOS）或
+CodeView（Windows）行号表。函数符号保留源码名（如 `xt_fn_3_add`），每条语句都有
+对应的行位置：
+
+```bash
+xbintsc build app.ts --debug
+gdb ./build/app          # 或 lldb ./build/app，Windows 用 WinDbg 打开 .exe
+```
+
+调试版二进制更大，并且与普通构建分开缓存（debug 标志参与缓存键）。`Error.stack`
+不需要 `--debug` 也能工作。
+
 ## 看起来不对、其实正常的构建行为
 
 ### 构建打印了 `(cached)` 并什么都没做
@@ -133,8 +166,9 @@ clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——
 
 ### 程序输出顺序出乎意料
 
-`async`/`await` 是同步微任务模型，且事件循环只在程序主体之后运行，所以定时器和套接字
-回调会晚触发；见 [language-support.md](./language-support.md)。
+`async`/`await` 只在 **pending** Promise 上挂起；等待已 settle 的值会同步继续，而 Node
+会排入微任务，因此顺序可能不同。事件循环仍在程序主体之后启动，定时器与套接字回调依然
+在主体之后触发；见 [language-support.md](./language-support.md)。
 
 ## 该去源码哪里看
 

package/doc/implemented.md

@@ -198,7 +198,7 @@ xt_value fn(xt_value thisValue, xt_value env, int32_t argc, xt_value *argv);
 
 - `thisValue` is threaded as the first ABI parameter (exception-safe, supports nesting); arrow functions inherit `this` lexically from an extra environment slot.
 - Closures thread captured variables through `env` (by reference, boxed); direct calls and closure calls share one code path.
-- `xt_object` carries a prototype field, and property lookup walks the prototype chain; `xt_function` carries a `prototype` and a property bag (static members).
+- `xt_object` carries a prototype field, and property lookup walks the prototype chain; `xt_function` carries a `prototype` and a property bag (static members). `xt_array` also carries a `[[Prototype]]` (Array.prototype). `Object.prototype` is the root of ordinary objects and provides `hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`; `Object.getPrototypeOf({}) === Object.prototype`.
 
 ---
 
@@ -219,16 +219,17 @@ Location: `src/codegen/llvm.ts`
   - Array literals (including spread `[...]`), object literals (including shorthand / methods / object spread `{...obj}`)
   - Typed arrays (`Uint8Array`, `Int8Array`, `Uint8ClampedArray`, `Uint16Array`, `Int16Array`, `Uint32Array`, `Int32Array`, `Float32Array`, `Float64Array`): construction (`new X(n)` / `new X(iterable)` / `X.from` / `X.of`), `length` / `byteLength` / `byteOffset` / `BYTES_PER_ELEMENT`, element reads/writes with per-type coercion (`ToIntN` / `ToUintN`, `Uint8ClampedArray` rounding, `Float32` single-precision rounding) and the prototype methods `fill` / `set` / `slice` / `subarray` / `join` / `toString` / `indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` / `some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` / `at` / `keys` / `values` / `entries`. See the unimplemented document for the deliberate divergences (`subarray` copies, iterator methods return arrays, no `ArrayBuffer`/`DataView`).
   - Property access (with a `length` special case, `Math` constants), element access, calls
+  - First-class built-in constructors (`const A = Array`, `const M = Map`, `const E = TypeError`, typed arrays): a bare reference lowers to `xt_builtin_constructor`, giving a cached function with `name` / `length`, a `prototype`, and its statics (`A.isArray`, `A.from`, `M.prototype`, ...). Calling or `new`-ing an alias dispatches to the same runtime constructor, and `x instanceof A` walks the shared prototype chain.
   - Optional chaining `?.` / `?.[]` / `?.()`: nullish check short-circuits to `undefined`
   - `delete`, `in`, `instanceof`
   - `this` (saved to the function's `%saved.this`; arrow functions read from an environment slot), `super` (`super.x` / `super(...)`), `new`, `await`
   - Closures (arrow functions / function expressions) and capture environment construction
 - Classes: constructor closure + prototype object, stored in an LLVM global (`@class.<id>`); instance fields are initialized before the constructor body; `static` members live in the constructor's property bag; `extends` sets up the prototype chain; `super(...)` is invoked through a hidden `__ctor` on the prototype.
-- `async`: wrapped with `xt_promise_resolve` before returning; `await` calls `xt_await` (drives the microtask queue and raises an exception on rejection).
+- `async`: closures are marked with `xt_function_set_async`; calling one runs the body on a stackful coroutine (`xt_coroutine.c`, `xt_async.c`) and immediately returns a promise. The body runs synchronously until the first `await` of a pending promise, then suspends; settlement queues a microtask that resumes the coroutine. An exception that escapes the body rejects that promise instead of throwing synchronously. `await` on a non-promise or settled promise keeps the synchronous fast path and raises on rejection.
 - Standard library calls: `console.*`, `Math.*`, `Object.*`, array / string methods all go through `xt_call_method` / `xt_math_call` / `xt_object_*`; `JSON`/`Date`/`Map`/`Set`/`RegExp`/`Promise` statics and constructors go through their `xt_*` functions; global functions (`parseInt`, `setTimeout`, etc.) go through `xt_parse_int`, `xt_set_timeout`, etc.
 - Global string pool (`@.str.N` private constants, UTF-8 escaped).
 - Builtin calls: `console.log` / `info` / `warn` / `error`, `Math.*`, `Object.*`, array / string methods, global functions, extension builtins (uniform `(argc, argv)` ABI).
-- `main` entry point (returns 0, calls the module function, and runs `xt_drain_microtasks` before returning).
+- `main` entry point (returns 0, calls the module function, then drains microtasks and runs the event loop until no timers or descriptors remain).
 - Unsupported nodes uniformly report `UnsupportedFeature`; they never crash.
 
 ---
@@ -236,18 +237,19 @@ Location: `src/codegen/llvm.ts`
 ## 8. C runtime (Runtime, implemented)
 
 Location: `runtime/xt_alloc.c`, `runtime/xt_values.c`, `runtime/xt_containers.c`,
-`runtime/xt_stdlib.c`, `runtime/xt_stdlib2.c`, `runtime/xt_promise.c`, `runtime/xt_builtins.c`,
+`runtime/xt_stdlib.c`, `runtime/xt_stdlib2.c`, `runtime/xt_promise.c`, `runtime/xt_async.c`,
+`runtime/xt_coroutine.c`, `runtime/xt_builtins.c`,
 `runtime/xt_io.c`, sharing the private header `runtime/rt_internal.h`; the public ABI is in `runtime/rt.h`.
 
 - Allocator: non-moving mark-sweep collector behind `xt_alloc` (explicit roots, subsystem root providers and a conservative C-stack scan).
 - Value construction: `xt_undefined/xt_null/xt_bool/xt_number/xt_string_new/xt_string_from_cstr`.
-- Strings: UTF-8 storage, concatenation, equality comparison, formatted number-to-string.
+- Strings: UTF-8 storage exposed through JavaScript's UTF-16 view (`length`, indexing, `slice`, `indexOf`, `split`, `padStart` and `codePointAt` count code units; `for...of` and `Array.from` count code points; lone surrogate halves are kept as WTF-8 and recombined on concatenation), lazy cons-node concatenation (bytes are flattened on first observation, so append loops stay linear), equality comparison, formatted number-to-string. `xt_string_length` reports bytes for I/O; `xt_string_utf16_length` reports the JavaScript length.
 - Type conversion: `xt_truthy`, `xt_to_number`, `xt_to_string`, `xt_typeof`.
 - Arithmetic: `add/sub/mul/div/mod/pow/neg/pos`.
 - Bitwise: `and/or/xor/not/shl/shr/ushr` (including `ToInt32` semantics).
 - Comparison: `lt/le/gt/ge`, loose / strict equality, `not`, `is_nullish`.
 - Objects: linear property list, `object_new/get/set/has/keys/values/entries/assign/spread`.
-- Arrays: `array_new/get/set/push/length/spread`; assigning `arr.length` truncates or extends (matching JS); `iter_length` / `iter_value` expose a uniform iteration view over arrays, strings, `Map` and `Set`.
+- Arrays: `array_new/get/set/push/length/spread`; assigning `arr.length` truncates or extends (matching JS); `iter_length` / `iter_value` expose a uniform iteration view over arrays, strings (by code point), `Map` and `Set`.
 - Typed arrays (`xt_typed_array.c`): typed arrays as property-bag objects with one prototype per element kind; element reads return the stored value and writes are coerced to the element type; `from` / `of` statics plus the full prototype method set; `subarray` copies.
 - Symbols (`xt_symbol.c`): `Symbol(description)` primitives (`XT_OBJECT_KIND_SYMBOL`), the 13 well-known symbols (`Symbol.iterator`, `Symbol.asyncIterator`, `Symbol.match`, …), `Symbol.for` / `Symbol.keyFor` global registry, `symbol.description` / `toString()` / `valueOf()`; symbols are valid property keys (`Object.getOwnPropertySymbols`, symbol keyed `get`/`set`/`in`/`delete`), are skipped by `Object.keys` / `values` / `entries` / `for...in` / `JSON.stringify`, and print as `Symbol(desc)`.
 - Generic member access: `xt_get` / `xt_set` (dispatch over arrays / objects / strings).
@@ -255,12 +257,13 @@ Location: `runtime/xt_alloc.c`, `runtime/xt_values.c`, `runtime/xt_containers.c`
 - Operator helpers: `xt_in` (`in`), `xt_delete` (`delete`), `xt_rest_args` (rest parameters / `arguments`).
 - Box: `box_new/get/set` (for closure-captured variables).
 - Functions and closures: `arg`, `closure_new/call/env/arity`.
-- Exceptions: `xt_try_enter` / `xt_try_exception` / `xt_try_leave` maintain the `_setjmp` frame stack; `xt_throw` long-jumps to the nearest `try` when a frame exists, otherwise prints `Uncaught ...` and exits.
+- Exceptions: `xt_try_enter` / `xt_try_exception` / `xt_try_leave` maintain the `_setjmp` frame stack; `xt_throw` long-jumps to the nearest `try` when a frame exists, otherwise prints `Uncaught ...` and exits. Codegen also maintains a shadow call stack (function name, source file and line): `Error.stack` captures it, and a fatal-signal handler dumps the same frames on a native crash. `--debug` additionally emits `!DICompileUnit` / `!DISubprogram` / `!DILocation` metadata and compiles with `-g -fno-omit-frame-pointer`, so gdb/lldb/WinDbg map instructions back to source lines.
 - Output: `xt_print/xt_println/xt_console_log/info/warn/error` (Node-style inspect: arrays `[ a, b ]`, objects `{ k: v }`; `info`/`log` to stdout, `warn`/`error` to stderr), plus `dir/trace/assert/count/countReset/group/groupEnd/table/time/timeEnd/timeLog`.
-- Objects / functions: `xt_object` with a prototype chain, `xt_function` with a property bag (static members and `prototype`); `xt_new` (instantiation), `xt_instance_of` (prototype chain), `xt_object_freeze/is_frozen/from_entries`.
+- Objects / functions: `xt_object` with a prototype chain, `xt_function` with a property bag (static members and `prototype`); `xt_new` (instantiation), `xt_instance_of` (prototype chain), `xt_object_freeze/is_frozen/from_entries`; `xt_constructors.c` holds the first-class constructor cache, constructor prototypes and static-value dispatch.
 - Standard library extensions (`xt_stdlib2.c`): extended array / string / number / object methods; `Object` / `Array` / `Number` / `String` statics; `JSON.parse` / `JSON.stringify`; `Map` / `Set`; `Date` (`gmtime_r`); `RegExp` (POSIX ERE `regcomp`/`regexec` `test`/`exec`).
-- Promise (`xt_promise.c`): synchronous microtask queue (`xt_microtasks`); `xt_promise_ctor/resolve/reject/static`, instance `then/catch/finally`; `xt_await` drives the queue until settle, and rejection raises via `xt_throw`; `xt_drain_microtasks` empties the queue at program exit.
-- Fetch (`xt_fetch.c`): global `fetch(input, init)` is a blocking HTTP/1.1 client whose promise is already settled (the runtime has no event loop). It accepts `http://` URLs only — `https://` rejects with a `TypeError` because no TLS backend is linked — and supports `method`, `headers` (plain object or `Headers`), `body` and `redirect` (`follow` / `manual` / `error`), following up to 20 redirects and switching POST to GET on 301/302/303. The resolved `Response`-shaped object exposes `ok` / `status` / `statusText` / `url` / `headers` plus `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`, and `Headers` is case-insensitive with `get` / `has` / `set` / `append` / `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`. Invalid URLs and network failures reject with a `TypeError`.
+- Promise (`xt_promise.c`): microtask queue (`xt_microtasks`); `xt_promise_ctor/resolve/reject/static`, instance `then/catch/finally`; `xt_drain_microtasks` empties the queue at program exit and the event loop drains it between callbacks. `xt_await` (in `xt_async.c`) returns a settled value synchronously, or suspends the running async coroutine and registers a waiter when the promise is pending.
+- Async coroutines (`xt_async.c`) on the shared stackful-coroutine runtime (`xt_coroutine.c`, POSIX `ucontext` / Windows fibers): each `async` call owns a private stack, swaps its `try` frame stack and GC stack region, and survives `await` across `try`/`finally`, loops and closures. A promise settled from a timer, a socket callback or another coroutine resumes the suspended body on the microtask queue.
+- Fetch (`xt_fetch.c`): global `fetch(input, init)` is a blocking HTTP/1.1 client whose promise is already settled (the exchange happens synchronously; it is not scheduled on the reactor). It accepts `http://` URLs only — `https://` rejects with a `TypeError` because no TLS backend is linked — and supports `method`, `headers` (plain object or `Headers`), `body` and `redirect` (`follow` / `manual` / `error`), following up to 20 redirects and switching POST to GET on 301/302/303. The resolved `Response`-shaped object exposes `ok` / `status` / `statusText` / `url` / `headers` plus `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`, and `Headers` is case-insensitive with `get` / `has` / `set` / `append` / `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`. Invalid URLs and network failures reject with a `TypeError`.
 
 ---
 
@@ -346,7 +349,7 @@ const result = build("program.ts", { emit: "exe", outDir: "build" });
 Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`)
 
 - Per-module unit tests; when `clang` is present, e2e really compiles and runs binaries, otherwise it is skipped automatically.
-- e2e coverage: arithmetic and printing, recursive functions, loops / arrays / string concatenation, closures capturing by reference, JS-style printing of objects / arrays, the Node `fs` extension via `import`, `switch` fall-through, array / string methods, `Math` and global functions and all `console` levels, default / rest parameters and `arguments`, `Object` helpers and spread and `in`/`delete`, `for...in` object key enumeration, `try/catch/finally`, optional chaining, classes and `new`/`this`/`static`/`extends`/`super`/`instanceof`, `async`/`await` and `Promise`, `Map`/`Set`/`JSON` and extended standard library, `for...of` over `Map`/`Set`, array `length` assignment and iterable spread, multi-file `import`/`export` (including `.js` specifiers and plain JavaScript sources), destructuring bindings and assignments, `enum`/`const enum`, regular-expression literals and `new Error(...)`, the `Error` family and `AggregateError`, generators and `Symbol` with custom `Symbol.iterator` iterables, typed arrays (element coercion, `from`/`of`, iteration and the prototype methods), and the global `fetch` (HTTP GET/POST, headers, redirects, JSON/text/binary bodies and `TypeError` rejection).
+- e2e coverage: arithmetic and printing, recursive functions, loops / arrays / string concatenation, closures capturing by reference, JS-style printing of objects / arrays, the Node `fs` extension via `import`, `switch` fall-through, array / string methods, `Math` and global functions and all `console` levels, default / rest parameters and `arguments`, `Object` helpers and spread and `in`/`delete`, `for...in` object key enumeration, `try/catch/finally`, optional chaining, classes and `new`/`this`/`static`/`extends`/`super`/`instanceof`, `async`/`await` and `Promise`, real await suspension (timers, TCP sockets and `fs/promises` across event-loop turns, rejection and `finally` after resuming), `Map`/`Set`/`JSON` and extended standard library, `for...of` over `Map`/`Set`, array `length` assignment and iterable spread, multi-file `import`/`export` (including `.js` specifiers and plain JavaScript sources), destructuring bindings and assignments (including object rest), built-in `instanceof`, `enum`/`const enum`, regular-expression literals and `new Error(...)`, the `Error` family and `AggregateError`, generators and `Symbol` with custom `Symbol.iterator` iterables, typed arrays (element coercion, `from`/`of`, iteration and the prototype methods), first-class built-in constructors and `Object.prototype` (aliases, statics, `getPrototypeOf`, `hasOwnProperty.call`), and the global `fetch` (HTTP GET/POST, headers, redirects, JSON/text/binary bodies and `TypeError` rejection).
 
 ---
 
@@ -360,11 +363,11 @@ Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `exte
 | Operators | Arithmetic, comparison, equality, logical, bitwise, shift, unary (including `typeof`/`void`), prefix/postfix increment-decrement, compound assignment, logical assignment, `in`, `delete`, `instanceof` |
 | Functions | Default parameters, rest parameters, capturing closures, `this` binding, lexical `this` in arrow functions, `call`/`apply`/`bind`, `name`/`length` |
 | Classes / OO | Constructors, instance fields, methods, `static`, inheritance `extends`/`super`, prototype chain, `instanceof` |
-| Async | `async`/`await`, `Promise` (`then/catch/finally`, `resolve/reject/all/allSettled/race`), synchronous microtask queue |
+| Async | `async`/`await` with real stackful-coroutine suspension (a pending promise pauses the body until a timer/socket/coroutine settles it), `Promise` (`then/catch/finally`, `resolve/reject/all/allSettled/race`) |
 | Modules | `import`/`export` (named / default / re-export / `export *` / `export type`), multi-file bundling over relative paths (`.js`-family specifiers resolve to their `.ts` sources, and TypeScript suffixes are preferred over JavaScript siblings when the specifier omits the extension; plain `.js` / `.jsx` / `.mjs` / `.cjs` sources are bundled directly too) and `node_modules` packages (`exports` / `module` / `main`, scoped packages and subpaths), bare specifiers resolved to extension modules; CommonJS packages under `node_modules` are lowered (`require` / `module.exports` / `exports`), while `require()` in user code is rejected with an `import` hint |
 | Standard library | Array / string / number / object extension methods, typed arrays, `Math`, `JSON`, `Date`, `RegExp`, `Map`, `Set`, `Symbol`, `Error` family, `Object/Array/Number/String/Symbol` statics, `console.*` |
 | Value model | 64-bit NaN-boxing, uniform function ABI (including `this`), closure environments, object prototype chains |
-| Runtime | Strings / objects / arrays / typed arrays / closures / arithmetic / comparison / catchable exceptions / Promise / collections / symbols / generators / `fetch` / `console` |
+| Runtime | Strings / objects / arrays / typed arrays / closures / arithmetic / comparison / catchable exceptions / Promise / async coroutines / collections / symbols / generators / `fetch` / `console` |
 | Extensions | Extension registry, `core` (print), `node` (fs / path / os / process / buffer / stream / net / dgram / http imported by specifier) |
 | GUI (`gui` extension) | Self-hosted HTML/CSS renderer window (SDL3 + SDL_GPU): DOM/CSS/layout, CSS `transform`/`transform-origin`, `<img>`/SVG, `<video>`/`<audio>`, `<canvas>` 2D, events, transitions (including `transform`) |
 | Toolchain | clang compiles IR/C, linking, incremental cache |

package/doc/requirements.md

@@ -20,10 +20,19 @@ build/app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but expected
 ```
 
 Typed pointers were removed in LLVM 16 ([release notes](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)),
-so check `clang --version` before anything else, and point xbintsc at a newer
-build with `xbintsc_CLANG` when the system clang is older. `xbintsc doctor`
-reports the resolved toolchain and its version. Working around the limitation by
-compiling the IR elsewhere is not supported.
+so xbintsc now **checks the version before it compiles anything**:
+
+- `xbintsc build` / `run` stop immediately with an actionable error when the
+  resolved driver is older than 16, instead of emitting IR that cannot compile.
+- `xbintsc doctor` prints `status : ok` or `status : too old` and exits non-zero
+  when the toolchain cannot build binaries, so scripts and CI can preflight it.
+- The search prefers a clang >= 16: on Windows the LLVM bundled with Visual
+  Studio (`<VS install>\VC\Tools\Llvm\x64\bin\clang.exe`) is found even when an
+  older `clang` comes first on `PATH`. Set `xbintsc_CLANG` to override the
+  choice; an explicit older binary is rejected with a "too old" error rather
+  than silently ignored.
+
+Working around the limitation by compiling the IR elsewhere is not supported.
 
 ## Summary
 

package/doc/unimplemented.md

@@ -68,8 +68,9 @@ None — generators are implemented.
 > Tagged templates are implemented, including raw strings and `String.raw`.
 > Generators (`function*`, `yield`, `yield*`) are implemented with stackful
 > coroutines, including `next`/`throw`/`return`, `for...of`, spread and
-> delegation. `import.meta` is parsed but has no runtime value; `async`
-> generators are not yet supported.
+> delegation. `import.meta` exposes `url`, `dirname` and `filename`, resolved
+> from the running executable's path. `async function*` is **rejected with
+> `UnsupportedFeature`** instead of silently producing a synchronous generator.
 
 ### 2.2 Not supported by the parser
 
@@ -79,7 +80,7 @@ None known at the expression level.
 
 | Operator | Status | Notes |
 | --- | --- | --- |
-| `new.target` | ✗ | not implemented |
+| `new.target` | ✗ | parsed, then rejected with `UnsupportedFeature` (no `new.target` semantics) |
 | `typeof` / `void` / `in` / `delete` / `instanceof` | ✓ | mapped to runtime helpers (`xt_typeof`, `xt_in`, `xt_delete`, `xt_instance_of`) |
 
 ---
@@ -100,6 +101,7 @@ None known at the expression level.
 - `JSON.parse` / `JSON.stringify`
 - `Date`, `RegExp` (POSIX ERE subset with capture groups), `Map`, `Set`, `Promise`, `BigInt`
 - `Array` statics (`isArray/of/from`), `Object` statics, `Number` statics, `String` statics (`fromCharCode` / `fromCodePoint` / `raw`)
+- Built-in constructors as first-class values (`const A = Array`, `new A(...)`, `A.isArray`, `x instanceof A`) and `Object.prototype` (`hasOwnProperty`, `toString`, `valueOf`, `isPrototypeOf`, `propertyIsEnumerable`, `__proto__`), with `Object.getPrototypeOf({}) === Object.prototype`
 - `Error` family (`Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, `URIError`, `AggregateError`): `new`, `instanceof`, `extends`, `String(err)` / `err.toString()` and `.stack`
 
 ### 3.3 Still unimplemented
@@ -113,7 +115,7 @@ None known at the expression level.
 | `AggregateError` constructor | ✓ `new AggregateError(errors, message)`; `Promise.any` now rejects with one |
 | Iterator protocol / `Symbol.iterator` / custom `for...of` iterables | ✓ arrays, strings, `Map`, `Set`, generators and any object exposing `[Symbol.iterator]()` are iterable in `for...of` / spread |
 | Generators (`function*`, `yield`, `yield*`, `next`/`throw`/`return`) | ✓ implemented with stackful coroutines; `for...of`, spread and delegation supported. `return()` completes without running `finally` |
-| Timers | ✓ `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` on the core event loop (numeric ids, no `Timeout` object; no `setImmediate` / `queueMicrotask`) |
+| Timers | ✓ `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` on the core event loop (numeric ids, no `Timeout` object; no `setImmediate` / `queueMicrotask`). A promise settled from a timer can be awaited: the async body suspends on the pending promise and resumes when the timer fires |
 | I/O / process and other host APIs | only via extensions (e.g. Node `fs`) |
 
 ### 3.4 Typed arrays
@@ -132,7 +134,7 @@ element writes, and `fill` / `set` / `slice` / `subarray` / `join` / `toString`
 | `keys` / `values` / `entries` | ~ return arrays, not iterator objects |
 | `ArrayBuffer` / `DataView` / `.buffer` / `.byteOffset` semantics | ✗ no backing buffer type; `.byteOffset` is always 0 |
 | `BigInt64Array` / `BigUint64Array` | ✗ not implemented |
-| `instanceof Uint8Array` | ✗ global constructors are not first-class values, so `x instanceof Uint8Array` fails with `Cannot find name 'Uint8Array'` |
+| `instanceof` built-in constructors | ✓ `instanceof Array` / `Object` / `Map` / `Set` / `Date` / `RegExp` / `Promise` / `Error` family / typed arrays are recognised by name **and through a first-class constructor value** (`const A = Array; x instanceof A`); constructors can be stored, passed, aliased, called and used with `new` |
 | Typed-array views over a `Buffer` / `ArrayBuffer` | ✗ constructors copy from a length / array-like / typed array only |
 
 ---
@@ -168,12 +170,13 @@ element writes, and `fill` / `set` / `slice` / `subarray` / `join` / `toString`
 | Destructuring parameters / bindings | ✓ | ✓ implemented |
 | `arguments` object | ✓ (implicit) | ✓ implemented (arrow functions get their own parameters, not the outer function's `arguments`, unlike JS) |
 | `this` binding / method call semantics | ✓ | ✓ implemented (`this` is threaded as the first ABI parameter; arrow functions inherit lexically) |
-| `async` / `await` / Promise | ✓ | ✓ implemented (synchronous microtask model) |
-| `new.target` | ✗ | not implemented |
-| Generators / iterators / `yield` | ✓ implemented | `function*`, `yield`, `yield*`, `.next/.throw/.return`; `async` generators not supported |
+| `async` / `await` / Promise | ✓ | ✓ implemented with stackful-coroutine suspension: awaiting a pending promise pauses the body and the event loop resumes it (see the deviations table for the remaining differences) |
+| `new.target` | ✗ | parsed, then rejected with `UnsupportedFeature` (no `new.target` semantics) |
+| Generators / iterators / `yield` | ✓ implemented | `function*`, `yield`, `yield*`, `.next/.throw/.return`; `async` generators are rejected with `UnsupportedFeature` |
 | Closure `arity` | — | `xt_closure_arity` is always -1, never filled in |
 | `fn.call` / `fn.apply` / `fn.bind` | ✓ | ✓ implemented (the bound closure does not track partial-argument `length`) |
 | `fn.name` / `fn.length` | ✓ | ✓ implemented (inferred from the declaration / assignment / property key; bound functions use `"bound ..."` and adjusted arity) |
+| First-class built-in constructors (`const A = Array`, `new A(...)`, `typeof Map`) | ✓ | ✓ constructors are ordinary function values with `name`/`length`, a `prototype`, their statics (`A.isArray`) and the full `instanceof` protocol |
 | First-class built-in methods (`typeof arr.map`, `const f = arr.push`, `obj.method?.()`) | ✓ | ✓ implemented as *unbound* method values: reading `arr.map` yields a function, `arr.map?.(cb)` and `obj.method?.()` bind the receiver as `this`, and a detached call (`const f = arr.map; f(cb)`) throws exactly like JavaScript. Method `name`/`length` are exposed |
 | `fn.toString()` | ~ | returns a native-style placeholder (`function name() { [native code] }`) instead of the original source text |
 
@@ -221,8 +224,7 @@ These features **compile and run**, but the result does not fully match ECMAScri
 
 | Item | Deviation |
 | --- | --- |
-| String `length` | Counted in UTF-8 bytes, not UTF-16 code units (`"\u00e9".length` reports 1 instead of 2; `"\u{1F600}".length` reports 4 instead of 2; `codePointAt` likewise differs) |
-| `Object.getPrototypeOf({})` | Returns `undefined` instead of the `Object.prototype` object |
+| RegExp byte-oriented matching | The engine matches UTF-8 bytes: literal multi-byte text works, but `.` and character classes consume one byte per repetition (`\d` / `\w` stay ASCII). Offsets returned by `exec` / `search` / replacement callbacks are converted to UTF-16 code units |
 | Global RegExp `lastIndex` | `test` / `exec` do not advance or honour a caller-set `lastIndex` for `/g` / `/y` regexes |
 | String `normalize` / `structuredClone` | Not implemented |
 | First-class built-in methods | Implemented as unbound method values (see section 5); `fn.toString()` returns a placeholder rather than source text |
@@ -230,11 +232,11 @@ These features **compile and run**, but the result does not fully match ECMAScri
 | Array out-of-bounds / sparse | Out-of-bounds access returns `undefined`; assigning `arr.length` truncates / extends, but sparse holes are not tracked distinctly |
 | Memory management | Non-moving mark-sweep collector behind `xt_alloc`: explicit roots, subsystem root providers and a conservative C-stack scan. Single-threaded and stop-the-world; no moving/compaction or generational mode |
 | Function `arity` / argument count | No argument count validation; `fn.length` reports the declared arity but calls are never checked against it |
-| `async` / `await` | **Synchronous microtask model**: `await` on an already-settled promise continues synchronously. Timers and sockets run on the event loop only after the program body, so a promise settled from a timer callback cannot be awaited |
+| `async` / `await` | Real suspension on a stackful coroutine, but `await` on a value that is **already settled** continues synchronously instead of queueing a microtask as the specification requires, so interleaving with pending `.then` callbacks can differ. Top-level `await` blocks on the event loop rather than yielding the module body. `fs/promises` still performs the I/O synchronously before settling; `fetch` is blocking; `async` generators are unsupported |
 | `super` | `super.x` / `super(...)` takes the prototype of `this`'s prototype; single-level inheritance is correct, but depth > 1 may be inaccurate |
-| `Error.stack` | Not captured |
+| `Error.stack` | Function-level frames only: each frame is `at name (file:line)` with the function's declaration line (updated to the construction line for the innermost frame); no column numbers and no frames for generator / `async` bodies (they switch stacks) |
 | Module live bindings | Namespace imports and imported bindings are snapshots (see section 4) |
-| `import.meta` | Parsed but has no value |
+| `import.meta` | ✓ `import.meta.url` / `.dirname` / `.filename`, resolved from the executable path |
 
 > Number formatting, loose equality, `+` / relational `ToPrimitive`, whole-chain
 > optional chaining, `finally` on early exit and object-key ordering have all
@@ -252,7 +254,7 @@ These features **compile and run**, but the result does not fully match ECMAScri
 | Type checker | ✗ only diagnostic codes are defined; no checker |
 | Full standard library | partial: Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` implemented; String.normalize / structuredClone missing |
 | Multi-file module bundling | partial: relative-path `.ts` bundling, ESM `node_modules` packages, namespace imports and bare-specifier extension module imports implemented; circular dependencies / CommonJS / live bindings not implemented |
-| A real async runtime / event loop | ✗ (Promise is a synchronous microtask model) |
+| Real async runtime | ✓ `async`/`await` suspends on pending promises on the `select(2)` reactor: timers, TCP sockets and promise callbacks resume the coroutine. Still missing: truly asynchronous I/O scheduling (`fs/promises` blocks before settling), a non-blocking `fetch` and worker threads (workers are child processes) |
 | Windows binary artifact verification | adapted at the build layer (`.exe` suffix, link flag branch), verified in CI |
 | Precise ECMAScript number / string / comparison semantics | partial, see section 8 |
 
@@ -263,9 +265,9 @@ These features **compile and run**, but the result does not fully match ECMAScri
 ```
 Unimplemented (statements): namespace/module declarations
 
-Unimplemented (expressions): new.target, import.meta value
+Unimplemented (expressions): new.target (clear UnsupportedFeature)
 
-Unimplemented (functions): `fn.toString()` source text, async generators
+Unimplemented (functions): `fn.toString()` source text, async generators (rejected)
 
 Unimplemented (classes/OO): abstract/implements, access control,
                             parent/child #x collision
@@ -279,8 +281,8 @@ Unimplemented (modules): circular dependencies, live bindings, dynamic
 Unimplemented (type system): type checking, generic instantiation, assertion
                              semantics, optional-chaining narrowing
 
-Unimplemented (runtime): a real async event loop, UTF-16 string length,
-                         Object.prototype identity, global-regex lastIndex
+Unimplemented (runtime): asynchronous I/O scheduling,
+                         global-regex lastIndex
 
 Unimplemented (engineering): type checker
 ```

package/doc/zh-CN/DESIGN.md

@@ -39,13 +39,18 @@ xt_value fn(xt_value env, int32_t argc, xt_value *argv);
 ```
 
 `env` 通过 box 以引用方式传递捕获变量，直接调用与闭包调用共用一条代码路径。
-不易内联的 JS 语义（`+` 隐式转换、关系比较、属性访问、打印）委托给 `@xt_*` 运行时调用。
+不易内联的 JS 语义（`+` 隐式转换、属性访问、打印）委托给 `@xt_*` 运行时调用。
+数值算术与比较是例外：codegen 内联 double 快路径（`numeric.ts`），需要隐式转换时
+才调用运行时。
 
 ### 运行时
 
-`runtime/xt_runtime.c` 实现字符串、对象、数组、闭包、算术、比较、异常与
-类 Node 的 `console.log` 打印。现在 `xt_alloc` 背后使用非移动标记-清扫回收器
-（显式根、子系统根提供者与保守 C 栈扫描），其内部实现对编译器保持隔离。
+`runtime/` 实现字符串、对象、数组、闭包、算术、比较、异常与类 Node 的
+`console.log` 打印。它按职责拆分为多个编译单元（`xt_values.c`、
+`xt_containers.c`、`xt_stdlib.c`、`xt_builtins.c`、`xt_io.c`、`xt_alloc.c` 等），
+每个单元 `#include` 自己的实现片段（`.inc`），这样文件保持小巧而不改变链接范围。
+`xt_alloc` 背后使用非移动标记-清扫回收器（显式根、子系统根提供者与保守 C 栈扫描），
+其内部实现对编译器保持隔离。
 
 ### llc 的替代
 
@@ -92,13 +97,14 @@ xt_value fn(xt_value env, int32_t argc, xt_value *argv);
 同样覆盖：Windows 下 xbintsc 使用系统 clang 按 MSVC ABI 链接，示例即针对该 ABI 构建。
 参见 `examples/extensions/` 与 `runtime/xt_ext.h` / `runtime/xt_ext.rs`。
 
-## 自举路线
+## 自举
 
-编译器本身使用 TypeScript 编写并输出 IR 文本，`runtime` 已与编译器解耦。后续可
-用 TS 重写运行时，并由 xbintsc 编译自身，逐步达成自举。
+编译器已经能编译自身：`xbintsc build src/cli/main.ts --ext node` 会产出一个可用的
+`xbintsc` 二进制，且从第一代起生成的 IR 就是不动点。CI 会为每个支持的平台构建这些
+二进制并检查不动点。运行时仍使用 C；以后是否用 TS 重写只是可选项，并不是自举的前提。
 
 ## 测试
 
 按模块划分：`tests/lexer`、`tests/parser`、`tests/binder`、`tests/codegen`、
-`tests/driver`、`tests/extensions`、`tests/cli`、`tests/e2e`。e2e 会在存在
-`clang` 时真正编译并运行二进制，否则自动跳过。
+`tests/driver`、`tests/extensions`、`tests/cli`、`tests/e2e`。存在受支持的 clang
+（16+，与 `build` 使用的版本门槛一致）时，e2e 会真正编译并运行二进制，否则自动跳过。