xbintsc 0.3.35 → 0.3.49

package/doc/node-unimplemented.md

@@ -0,0 +1,167 @@
+# xbintsc Node Extension Unimplemented Features
+
+This document was compiled by checking the Node extension source
+(`src/extensions/node/`) and the C runtime (`runtime/ext_node/`) file by file,
+and lists the features that the **Node extension currently does not implement /
+is missing**.
+
+> Related documents:
+> - Core language capabilities: [implemented.md](./implemented.md) / [unimplemented.md](./unimplemented.md)
+> - Implemented parts of the Node extension: [node-implemented.md](./node-implemented.md)
+
+> Language: **English** | [简体中文](./zh-CN/node-unimplemented.md)
+
+---
+
+## 1. Unimplemented in the `fs` module
+
+`fs` now implements the **synchronous** API surface (files, directories,
+descriptors, metadata, links, `cp`, `glob`, `Dir`, `constants`) and
+`fs/promises` wraps each synchronous function in an already-settled Promise
+(see [node-implemented.md](./node-implemented.md)). The rest is still
+unimplemented because xbintsc has **no asynchronous I/O scheduler** for file
+operations (the `fs` module has no reactor backend; the core event loop does
+provide timers and sockets):
+
+| Unimplemented API | Category |
+| --- | --- |
+| `readFile` / `writeFile` / `appendFile` / `open` / `close` / `read` / `write` / `stat` / … | callback-style async file operations (`fs/promises` provides the Promise forms) |
+| `createReadStream` / `createWriteStream` | streaming read/write |
+| `watch` / `watchFile` | **real** file watching: the functions exist but the returned objects never emit (there is no inotify/kqueue backend) |
+| `openAsBlob`, `statfs` callback form, `rmdir` `maxRetries` / `retryDelay` | misc. options requiring async retry |
+| `glob` `exclude` / `follow`, `cp` `filter` | option callbacks |
+
+### 1.1 Read semantics gaps
+
+- `readFileSync` supports encoding options (default/`utf8`/`ascii`/`latin1`/`binary`/ `hex`/`base64`/`base64url`), but **does not return a `Buffer`** by default: even though `Buffer` exists (simulated as a plain object), `readFileSync` still returns a string. Pass a `Buffer`-producing path or read raw bytes explicitly.
+- `utf16le` / `ucs2` decoding is not implemented (the bytes are returned as text).
+- `watch` / `watchFile` / `unwatchFile` return API-shaped emitter objects whose `.close()` / `.on()` methods exist but which **never fire** events.
+- `Dir.read(cb)` / `Dir.close(cb)` and the async form of `FileHandle` methods complete **synchronously** (the callback/Promise is invoked immediately).
+- `mkdtempSync` always appends 6 random characters to the prefix (it does not require a trailing `XXXXXX`).
+- `globSync` supports `*`, `?`, `[...]` and `**` but not the `exclude` callback or `follow`; `**` does not descend through symlinks (matching Node's default).
+- `cpSync` symlink handling follows Node for the common cases but `verbatimSymlinks` is not supported.
+- Platform deviations: on Windows `readlinkSync` raises `ENOSYS` and `chmodSync` / `lchmodSync` / `chownSync` / `lchownSync` / `fchmodSync` / `fchownSync` are no-ops; `statfsSync` returns zeroed fields on Windows/AIX/Sun; `lutimesSync` falls back to `utimesSync` on macOS/Windows.
+
+---
+
+## 2. Other Node modules fully unimplemented
+
+The following Node built-in modules have no corresponding extension / builtin
+(`fs` / `fs/promises` / `path` / `os` / `process` / `buffer` / `stream` /
+`dgram` / `http` / `events` / `util` / `querystring` / `assert` / `test` are
+implemented, and `crypto` / `url` / `child_process` / `zlib` /
+`stream/promises` / `worker_threads` are partially implemented; see
+[node-implemented.md](./node-implemented.md)):
+
+| Module | Notes |
+| --- | --- |
+| `https` | TLS version of HTTP |
+| `readline` | command-line reading |
+| `tls` / `cluster` / `vm` / `os` (partially) etc. | other modules not listed |
+
+> `crypto` (only `createHash`, now with the streaming API), `url` (only
+> `pathToFileURL` / `fileURLToPath`), `child_process` (only `spawnSync`),
+> `zlib` (only `createGzip`) and `worker_threads` (only `Worker` /
+> `isMainThread` / `workerData` / `parentPort`) are partially implemented.
+
+---
+
+## 3. Node global objects / namespaces
+
+| Unimplemented | Notes |
+| --- | --- |
+| `global` / `globalThis` | none |
+| `__dirname` / `__filename` | none |
+| `require` / `module` / `exports` | only inside `node_modules` packages (the bundler lowers them); user code must use ESM `import` |
+| `fs.readFileSync(...)` without an `import` | ✗ unsupported. `fs` is not a global; import it first (`import fs from "fs"` or `import * as fs from "node:fs"`) and `fs.readFileSync(...)` lowers to the module's runtime symbol. |
+
+Node modules are reached through `import` with a bare or `node:`-prefixed
+specifier (`import { readFileSync } from "fs"`, `import path from "path"`,
+`import { platform } from "node:os"`). Named and namespace imports both resolve
+to the extension module's runtime entries.
+
+Supported namespace calls: `path.*`, `os.*`, `process.*`, `fs.*`,
+`fs/promises.*` (methods), `child_process.*`, `crypto.*`, `url.*` once imported
+(a namespace/default import or, for `path`/`os`/`process`, the global name),
+plus the dispatcher-backed namespaces `Buffer.*`, `stream.*`, `net.*`,
+`dgram.*`, `http.*` and properties such as `process.platform` /
+`process.argv`. `Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough`
+/ `Buffer` can also be used as global constructors.
+
+---
+
+## 4. Async / event loop model
+
+Implemented:
+
+- Core event loop `runtime/xt_loop.c` (a `select(2)` reactor); `net` / `dgram` / `http` are all built on it.
+- `Promise`, `async` / `await` are available (see the core documents); `fs/promises` returns Promises.
+- Timers are available as globals: `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` run on the core reactor and keep the process alive until no timer remains.
+- A standalone `EventEmitter` is provided by the `events` module (also a global constructor); streams and sockets additionally carry internal emitter methods (`on` / `addListener` / `once` / `off` / `removeListener` / `emit`).
+
+Still unimplemented:
+
+- `setImmediate` / `queueMicrotask` and Node's `Timeout` object (`setTimeout` returns a numeric id).
+- A real asynchronous I/O scheduler: `fs/promises` is essentially an immediate-settle wrapper around synchronous operations and does not yield while waiting for I/O.
+- On streams and sockets the built-in `once` is equivalent to `on` (no "remove after firing once" semantics); the `events` module's `EventEmitter` does implement real `once`.
+- `net`'s `connect` is blocking; HTTP responses require `Connection: close`, with no keep-alive / chunked transfer / pipelining.
+
+---
+
+## 5. Bun extension unimplemented
+
+The `Bun.file` and other Bun APIs mentioned in the design document are only
+design examples of the extension mechanism and are **not yet implemented**:
+
+- No `bun` extension directory, no Bun builtins, no Bun C runtime.
+- Under `src/extensions/` there is currently only the single platform extension `node` (plus the core extension).
+
+---
+
+## 6. Quick reference: Node extension unimplemented list
+
+```
+Implemented (fs): the full synchronous surface — readFileSync (with encoding), readTextFile,
+                  writeFileSync, appendFileSync, existsSync, readdirSync (withFileTypes/recursive),
+                  mkdirSync, rmSync, unlinkSync, rmdirSync, renameSync, copyFileSync, cpSync,
+                  realpathSync, statSync, lstatSync, statfsSync, accessSync, chmodSync, lchmodSync,
+                  chownSync, lchownSync, truncateSync, utimesSync, lutimesSync, mkdtempSync,
+                  linkSync, symlinkSync, readlinkSync, opendirSync (Dir), globSync, watch,
+                  watchFile, unwatchFile, constants,
+                  openSync, closeSync, readSync, writeSync, readvSync, writevSync, fstatSync,
+                  fsyncSync, fdatasyncSync, ftruncateSync, fchmodSync, fchownSync, futimesSync
+Implemented (fs/promises): readFile, writeFile, appendFile, mkdir, readdir, rm, unlink,
+                           rmdir, rename, copyFile, cp, realpath, stat, lstat, statfs, access,
+                           open (FileHandle), chmod, lchmod, chown, lchown, truncate, utimes,
+                           lutimes, link, symlink, readlink, mkdtemp, opendir, glob, watch, constants
+Implemented (other modules): path (join/resolve/normalize/dirname/basename/extname/isAbsolute/relative),
+                             os (platform/arch/type/release/endianness/homedir/tmpdir/hostname/totalmem/freemem/cpus),
+                             process (cwd/exit/uptime/hrtime/getuid/platform/arch/pid/ppid/argv/env/version/title),
+                             buffer (from/alloc/isBuffer/byteLength/concat/compare + instance methods),
+                             stream (Readable/Writable/Duplex/Transform/PassThrough, pipe),
+                             net (createServer/connect/isIP + Server/Socket),
+                             dgram (createSocket + bind/send/close/address),
+                             http (createServer/request/get + req/res),
+                             events (EventEmitter: on/once/off/emit/listeners/listenerCount/eventNames),
+                             util (format/inspect/isDeepStrictEqual/inherits/promisify + isX),
+                             querystring (parse/stringify/escape/unescape),
+                             crypto (createHash + streaming, SHA-1/SHA-256),
+                             url (pathToFileURL/fileURLToPath only),
+                             child_process (spawnSync only),
+                             zlib (createGzip only), stream/promises (pipeline only),
+                             worker_threads (Worker/isMainThread/workerData/parentPort only)
+
+Unimplemented (fs): callback-style async file operations (readFile/writeFile/appendFile/open/
+                    read/write/close), createReadStream/createWriteStream, real file watching
+                    (watch/watchFile objects never emit),
+                    glob exclude/follow, cp filter, utf16le decoding, Buffer return from readFileSync
+
+Unimplemented (other modules): https, readline, tls, cluster, vm
+
+Unimplemented (global/namespace): global/globalThis, __dirname, __filename,
+                                  require/module/exports, fs.readFileSync(...) namespace calls
+
+Unimplemented (async): setImmediate / queueMicrotask, real async I/O scheduling, keep-alive
+
+Unimplemented (platform): Bun extension (design example only)
+```

package/doc/post/announce.md

@@ -0,0 +1,43 @@
+# Guys, TypeScript can now be compiled into native binaries
+
+## Background
+
+Back in 2019 I spent some time studying compilers. I wrote a mini JS compiler that only supported the `function` and `number` types — but don't underestimate just those two types: it took me nearly two weeks to implement. That's when I realized a compiler demands an enormous amount of time and effort, and I sighed that I would probably never manage to build a relatively complete one in my lifetime.
+
+Then one afternoon in September 2026, someone in a group chat remarked that frontend / JS / TS will always sit at the very bottom of the food chain, because unlike C++ and Rust it can't produce binary files.
+
+## The Trigger
+
+It was like something in my core got triggered. A thought kept flooding my mind, so I went back and dug up the articles I had written about compilers back then. No! That's not right! If using Ai,it might actually be possible now. So I started laying out my ideas and wrote my first document, DESIGN.md. Then I opened pi and started hacking!
+
+Very quickly — in under an hour — the first prototype appeared. Looking at how ugly and simplistic it was, not even as good as the demo I wrote years ago, I decided to rewrite the entire framework from scratch. After several days I finally reached the level I wanted. Then I started a second attempt: I fired up pi again, and this time I found that although the AI was only so-so at architecture, once the architecture was in place it completed features unbelievably fast. So I kicked off a rapid iteration process.
+
+## Core Progress
+
+* The vast majority of JS/TS syntax plus mainstream Node.js APIs (as optional packages)
+* Support for C++ and Rust extensions, so users can freely extend it
+* Self-hosting achieved — it compiles itself
+* Runs with no GNU dependency
+
+Of course, what's not implemented is listed here:
+[unimplemented.md](https://github.com/zy445566/xbintsc/blob/main/doc/unimplemented.md)
+[node-unimplemented.md](https://github.com/zy445566/xbintsc/blob/main/doc/node-unimplemented.md)
+
+The biggest advantages of binary compilation come down to two things:
+* Tiny bundle size — the compiled binary is as small as 200 KB (--ext node 300KB) and runs directly, with no need to bundle a tens-of-MB Node.js runtime anymore
+* Blazing-fast cold start — measured on my machine at roughly 120–200× faster than native Node.js
+
+## Usage
+
+Download the zst archive from the [releases page](https://github.com/zy445566/xbintsc/releases), extract it, and run it. Here's a Windows example:
+```
+# Build
+.\xbintsc-win32-x64\bin\xbintsc.exe build .\hello.ts --out .\build
+# Run
+.\build\hello.exe
+```
+
+# Appendix
+
+GitHub: [https://github.com/zy445566/xbintsc](https://github.com/zy445566/xbintsc)
+If you're interested, let's dig into it together `;)`

package/doc/requirements.md

@@ -0,0 +1,145 @@
+# xbintsc Requirements
+
+This page lists what a machine needs in order for `xbintsc` to **compile and
+link native binaries**. xbintsc does not bundle a compiler, so every host needs
+a clang-compatible toolchain installed. `xbintsc emit` (pure LLVM IR text) has
+no requirements on any platform.
+
+## Minimum versions
+
+| Requirement | Minimum | Notes |
+| --- | --- | --- |
+| clang / LLVM | **16** | The emitted IR uses opaque pointers, which LLVM 16 made the only pointer representation. |
+| Node.js | **22** | Only to run or build the compiler from source; released binaries are standalone and need no Node. |
+
+clang 15 and older fail on the first string literal in any program, with:
+
+```
+build/app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but expected 'i8*'
+  %r0 = call i64 @xt_string_new(i8* @.str.0, i64 5)
+```
+
+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.
+
+## Summary
+
+| Platform | Requirement | Provided by |
+| --- | --- | --- |
+| Linux | `clang` + `lld` (a glibc distribution) | the user (package manager) |
+| macOS | **Xcode Command Line Tools** | the user (install once) |
+| Windows | **LLVM** + **Visual Studio C++ build tools** (MSVC ABI) | the user (install once) |
+| any | `xbintsc emit` | nothing |
+
+The Windows release targets the **MSVC ABI**: clang uses the
+Windows SDK and the MSVC C/C++ runtime/headers.
+
+## Prebuilt releases (recommended)
+
+Download the archive for your platform from
+[GitHub Releases](https://github.com/zy445566/xbintsc/releases/latest) (each one
+has a `.sha256` beside it):
+
+| Platform | Archive |
+| --- | --- |
+| Windows x64 / arm64 | `xbintsc-<version>-win32-x64.tar.zst` / `xbintsc-<version>-win32-arm64.tar.zst` |
+| Linux x64 / arm64 | `xbintsc-<version>-linux-x64.tar.zst` / `xbintsc-<version>-linux-arm64.tar.zst` |
+| macOS x64 / arm64 (Apple Silicon) | `xbintsc-<version>-darwin-x64.tar.zst` / `xbintsc-<version>-darwin-arm64.tar.zst` |
+
+(`.tar.gz` is used only when `zstd` is unavailable on the build machine.)
+
+`<version>` is the release version (for example `0.3.14`), embedded in the asset
+name so downloads from different releases do not collide.
+
+Every archive unpacks to the same layout:
+
+```text
+xbintsc-<os>-<arch>/
+  bin/xbintsc[.exe]      the compiler
+  runtime/               C runtime sources + prebuilt runtime/lib/<os>-<arch>/
+```
+
+Windows archives omit the prebuilt `runtime/lib/`; the driver compiles the C
+runtime on demand with the user's clang.
+
+Unpack it, put `bin/` on `PATH` (or call `bin/xbintsc` directly), and install the
+toolchain for your platform below. Verify the download against the checksum
+first:
+
+```sh
+sha256sum -c xbintsc-<version>-linux-x64.tar.zst.sha256   # macOS: shasum -a 256 -c
+```
+
+## macOS — install Xcode Command Line Tools
+
+xbintsc uses the linker and system SDK (`libSystem`, …) that ship with the
+Command Line Tools to produce executables. Install them once:
+
+```sh
+xcode-select --install
+```
+
+Verify:
+
+```sh
+xcode-select -p            # prints the active developer directory
+xcrun --show-sdk-path      # prints the SDK path
+```
+
+## Linux — install clang and lld
+
+A normal glibc-based distribution plus `clang` and `lld` is enough:
+
+```sh
+sudo apt-get install -y clang lld        # Debian / Ubuntu
+sudo dnf install -y clang lld            # Fedora / RHEL
+sudo pacman -S --needed clang lld        # Arch
+sudo zypper install -y clang lld         # openSUSE
+sudo apk add clang lld                   # Alpine
+```
+
+Verify with `clang --version`. If xbintsc uses the wrong linker, set
+`xbintsc_CLANG` to the clang you want and/or pass extra flags through
+`xbintsc_LINKER_ARGS` (for example `-fuse-ld=lld`).
+
+## Windows — install LLVM and the MSVC C++ build tools
+
+Install LLVM and the Visual Studio C++ build tools with `winget`:
+
+```powershell
+winget install -e --id LLVM.LLVM
+winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
+  --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+```
+
+clang needs the MSVC/SDK environment (`INCLUDE`, `LIB`, `PATH`) to find the C
+standard library headers, the import libraries and the linker. Open an
+**x64 Native Tools Command Prompt for VS 2022** (or an **ARM64 Native Tools**
+prompt on Windows on ARM) before running `xbintsc`, or import the environment
+yourself:
+
+```powershell
+& "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
+```
+
+Verify with `clang --version` (chocolatey also works: `choco install llvm`).
+
+## Building from source (contributors only)
+
+- Node.js ≥ 22 is required only to run/build the compiler itself. The released
+  standalone binaries do **not** need Node.
+- A C compiler is required to rebuild the runtime (`npm run runtime`).
+- `npm run package-release` assembles the per-platform release archive
+  (`xbintsc-<os>-<arch>.tar.{gz,zst}` + `.sha256`) into `dist/release/`.
+
+## Checking your environment
+
+```sh
+xbintsc doctor
+```
+
+`doctor` reports the resolved toolchain (env / system), its version and location,
+and the runtime-library directory.

package/doc/unimplemented.md

@@ -0,0 +1,286 @@
+# xbintsc Unimplemented Syntax and Features
+
+This document was compiled by checking the source (`src/`, `runtime/`) and tests
+(`tests/`) file by file, and lists the syntax and features that are
+**currently unimplemented / only partially implemented / semantically different
+from the standard**.
+
+Criteria (ordered by severity):
+
+1. **Not parsed**: the parser reports a syntax error immediately; code generation is never reached.
+2. **Parsed but codegen errors**: the AST / binding can be built, but `codegen` reports `UnsupportedFeature`.
+3. **Parsed and compilable, but semantics are missing or differ**: a binary is produced, but the runtime result does not match ECMAScript / TypeScript semantics.
+
+> Language: **English** | [简体中文](./zh-CN/unimplemented.md)
+
+> Recently completed: **ECMAScript semantics + differential testing** — number
+> formatting / coercion (`toFixed` / `toPrecision` / `toExponential`, hex / octal
+> / binary parsing, full `+` and relational `ToPrimitive`), `JSON.stringify`
+> omission rules, default `Array.prototype.sort` (stable, string order),
+> insertion-ordered integer keys, whole-chain optional chaining, `finally` on
+> early `return` / `break` / `continue`, object-key insertion order, UTF-8-aware
+> `console` inspection with circular references, `Array.prototype.splice`,
+> `String.prototype.match` / `lastIndexOf` / `split` with limit, RegExp capture
+> groups (`exec` / `match` / `replace` / `split` / `search`), immutable array
+> methods (`toReversed` / `toSorted` / `toSpliced` / `with`),
+> `Object.getOwnPropertyNames` / `groupBy`, global URI functions, labeled
+> statements, `#private` fields / methods / statics, tagged templates (with raw
+> strings and `String.raw`), and `import * as ns` for relative modules. The test
+> suite now includes a **differential harness** that runs every case through both
+> xbintsc and Node and compares output byte-for-byte.
+
+> Also completed: `class` declarations / class expressions, `new` / `this`,
+> inheritance `extends` / `super`, `instanceof`, methods / static members /
+> instance fields / getters and setters / constructor parameter properties,
+> `async` / `await` + `Promise`, multi-file `import` / `export` bundling
+> (including `.js` → `.ts` specifier resolution and namespace imports), `Map` /
+> `Set` / `Date` / `RegExp` / `JSON` / `BigInt`, destructuring bindings and
+> parameters, `enum` / `const enum`, and **self-hosting** (the emitted LLVM IR
+> reaches a byte-identical fixpoint).
+
+---
+
+## 1. Unimplemented at the statement level
+
+### 1.1 Parsed but codegen reports `UnsupportedFeature`
+
+| Syntax | Status | Notes |
+| --- | --- | --- |
+| `namespace` / `module` declarations | parse ✓, codegen ✗ | → "does not yet support this statement (module declaration)" |
+
+> Labeled statements (`label: statement`, `break label`, `continue label`) are
+> implemented, including labels on non-loop statements.
+
+### 1.2 Not supported by the parser (immediate syntax error)
+
+None known at the statement level. The parser is intentionally permissive and
+accepts most TypeScript statement syntax; unsupported forms are rejected later
+by code generation (see above).
+
+---
+
+## 2. Unimplemented at the expression level
+
+### 2.1 Parsed but codegen reports `UnsupportedFeature`
+
+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.
+
+### 2.2 Not supported by the parser
+
+None known at the expression level.
+
+### 2.3 Unimplemented operators
+
+| Operator | Status | Notes |
+| --- | --- | --- |
+| `new.target` | ✗ | not implemented |
+| `typeof` / `void` / `in` / `delete` / `instanceof` | ✓ | mapped to runtime helpers (`xt_typeof`, `xt_in`, `xt_delete`, `xt_instance_of`) |
+
+---
+
+## 3. Unimplemented standard library
+
+### 3.1 Implemented (summary)
+
+- Arrays: `push` `pop` `shift` `unshift` `join` `slice` `splice` `indexOf` `lastIndexOf` `includes` `concat` `reverse` `forEach` `map` `filter` `reduce` `reduceRight` `find` `findIndex` `findLast` `findLastIndex` `some` `every` `sort` `flat` `flatMap` `fill` `copyWithin` `at` `keys` `values` `entries` and the immutable `toReversed` / `toSorted` / `toSpliced` / `with`
+- Strings: `charAt` `charCodeAt` `codePointAt` `indexOf` `lastIndexOf` `includes` `startsWith` `endsWith` `slice` `substring` `substr` `split` `match` `replace` `replaceAll` `search` `toUpperCase` `toLowerCase` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `concat` `at` `localeCompare` `valueOf`
+- `Math`: full set of functions and constants
+- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`, object spread `{...obj}`
+- Global functions: `parseInt` `parseFloat` `isNaN` `isFinite` `Number` `String` `Boolean` `encodeURI` `decodeURI` `encodeURIComponent` `decodeURIComponent`
+- `console.log` / `info` / `warn` / `error` / `dir` / `trace` / `assert` / `count` / `group` / `table` / `time`
+
+### 3.2 Completed
+
+- `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`)
+- `Error` family (`Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, `URIError`, `AggregateError`): `new`, `instanceof`, `extends`, `String(err)` / `err.toString()` and `.stack`
+
+### 3.3 Still unimplemented
+
+| Category | Status |
+| --- | --- |
+| `Symbol` constructor and symbol primitives | ✓ `Symbol(description)`, well-known symbols, `Symbol.for` / `Symbol.keyFor`, symbol property keys and `Object.getOwnPropertySymbols` |
+| `String.prototype.normalize` | ✗ not implemented |
+| `structuredClone` | ✗ not implemented |
+| Built-in error subclasses (`TypeError`, `RangeError`, …) | ✓ first-class constructors and prototypes; `instanceof Error` holds for the whole family |
+| `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`) |
+| I/O / process and other host APIs | only via extensions (e.g. Node `fs`) |
+
+### 3.4 Typed arrays
+
+Implemented: `Uint8Array`, `Int8Array`, `Uint8ClampedArray`, `Uint16Array`,
+`Int16Array`, `Uint32Array`, `Int32Array`, `Float32Array`, `Float64Array` with
+`new X(n)` / `new X(arrayLike)`, `X.from` / `X.of`, `BYTES_PER_ELEMENT`, coerced
+element writes, and `fill` / `set` / `slice` / `subarray` / `join` / `toString` /
+`indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` /
+`some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` /
+`at` / `keys` / `values` / `entries`. Known divergences:
+
+| Feature | Status |
+| --- | --- |
+| `subarray` | ~ returns a copy, not a view over a shared buffer |
+| `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'` |
+| Typed-array views over a `Buffer` / `ArrayBuffer` | ✗ constructors copy from a length / array-like / typed array only |
+
+---
+
+## 4. Module system
+
+| Feature | Status |
+| --- | --- |
+| Multi-file / module resolution and linking | ✓ driver-layer AST bundling (`src/driver/modules.ts`): parse each module, rename top-level symbols by module prefix, rewrite references, merge into one file and rebind |
+| Named import/export | ✓ `import { a, b as c }` / `export { a as b }` / `export const/let/var/function/class` |
+| Default import/export | ✓ `export default` / `import d from` |
+| Re-export `export { x } from` / `export * from` | ✓ (`export *` copies the dependency's exports) |
+| Namespace import `import * as ns` | ✓ lowered to a synthetic object literal holding every export |
+| Circular dependencies | ✗ errors out (no circular initialization semantics) |
+| Live bindings | ✗ namespace objects and imported bindings are snapshots at module-evaluation time |
+| ESM `node_modules` packages | ✓ bare specifiers resolve up the tree through `exports` / `module` / `main`, including scoped packages and subpaths; the package sources are bundled like relative modules |
+| CommonJS `require` / `module.exports` | ✓ inside `node_modules` only: the bundler gives each CommonJS package a synthetic `module` / `exports` pair, lowers `require("x")` to the bundled dependency's exports, and hoists external/built-in `require`s into ESM imports. `require()` in user code (outside `node_modules`) is still rejected with a diagnostic pointing at the ESM `import` form. |
+
+> Extension modules (such as `fs`) are importable by bare or `node:`-prefixed
+> specifier — `import { readFileSync } from "fs"` / `import path from "path"` —
+> and resolve to their runtime entries (named, default and namespace forms).
+> Relative modules and ESM packages under `node_modules` are bundled at the driver layer.
+
+---
+
+## 5. Unimplemented function features (or missing semantics)
+
+| Feature | Parse | Semantics |
+| --- | --- | --- |
+| Default parameters `function f(a = 5)` | ✓ | ✓ implemented |
+| Rest parameters `function f(...args)` | ✓ | ✓ implemented |
+| Spread in call arguments `f(...args)` | ✓ | ✓ implemented |
+| 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 |
+| 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 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 |
+
+---
+
+## 6. Classes and object orientation
+
+| Feature | Status |
+| --- | --- |
+| `class` declarations / class expressions | ✓ implemented |
+| `constructor` | ✓ |
+| Instance fields / property declarations | ✓ |
+| Methods | ✓ |
+| `static` fields / methods | ✓ |
+| Inheritance `extends` / `super` | ✓ (single level correct; `super` takes the prototype of `this`'s prototype — see section 8) |
+| Prototype chain / method lookup | ✓ |
+| `instanceof` | ✓ |
+| `new` / instantiation | ✓ |
+| `get` / `set` accessors | ✓ implemented |
+| Parameter properties `constructor(public x: T)` | ✓ implemented |
+| Private fields `#x` | ✓ implemented (stored under a literal `#x` key; no accessibility enforcement) |
+| `enum` / `const enum` | ✓ implemented (forward + reverse mapping) |
+| `private` / `protected` / `public` / `readonly` modifiers | ✗ no access control (erased) |
+| `abstract` / `implements` | ✗ (erased) |
+| Parent/child `#x` name collisions | ✗ may alias (same literal key) |
+
+---
+
+## 7. Unimplemented type system (parsed only, not checked)
+
+Type syntax is parsed into the AST and then **erased entirely** during binding /
+code generation; no type checking is performed:
+
+- Type annotations, return types, type parameters, type aliases, interfaces, generic constraints, etc.: parse ✓, check ✗.
+- Checker diagnostic codes (`TypeMismatch` `NotCallable` `PropertyNotFound` `ArgumentCountMismatch`) are defined but **unused**.
+- `as` / `satisfies` / non-null assertion `!`: erased directly, no assertion semantics.
+- Generics: no runtime instantiation; type parameters are ignored.
+- Optional chaining `?.` type narrowing: none (runtime short-circuit is implemented, but there is no type-level narrowing).
+
+---
+
+## 8. Runtime / semantics differing from the standard (known deviations)
+
+These features **compile and run**, but the result does not fully match ECMAScript:
+
+| 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 |
+| 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 |
+| `for...in` | Enumerates own keys of objects / arrays / strings; does not include prototype-chain properties |
+| 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 |
+| `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 |
+| Module live bindings | Namespace imports and imported bindings are snapshots (see section 4) |
+| `import.meta` | Parsed but has no value |
+
+> Number formatting, loose equality, `+` / relational `ToPrimitive`, whole-chain
+> optional chaining, `finally` on early exit and object-key ordering have all
+> been brought in line with Node and are covered by the differential tests, so
+> they are no longer listed as deviations.
+
+---
+
+## 9. Unimplemented toolchain / platform / engineering
+
+| Item | Status |
+| --- | --- |
+| GC (garbage collection) | ✓ non-moving mark-sweep in `xt_alloc.c`, armed by a live-heap threshold (`XT_GC_THRESHOLD`) or `xt_gc_collect()`; explicit roots + root providers + conservative active-stack scan. No compaction, weak references or background collection |
+| Self-hosting | ✓ the compiler compiles itself: `xbintsc build src/cli/main.ts` produces a working binary, and the emitted IR is stable from generation 1 onward. The runtime is still C |
+| 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) |
+| 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 |
+
+---
+
+## 10. Quick reference: unimplemented / partially implemented list
+
+```
+Unimplemented (statements): namespace/module declarations
+
+Unimplemented (expressions): new.target, import.meta value
+
+Unimplemented (functions): `fn.toString()` source text, async generators
+
+Unimplemented (classes/OO): abstract/implements, access control,
+                            parent/child #x collision
+
+Unimplemented (standard library): String.normalize, structuredClone
+
+Unimplemented (modules): circular dependencies, live bindings, dynamic
+                           `require(expr)`, `require.resolve` / `require.cache`,
+                           `__dirname` / `__filename`
+
+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 (engineering): type checker
+```