xbintsc 0.5.6 → 0.5.21

package/doc/node-unimplemented.md

@@ -1,167 +1,6 @@
-# xbintsc Node Extension Unimplemented Features
+# Node extension: unimplemented (moved)
 
-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)
+This page moved to [Node extension: unimplemented](./unimplemented/node.md).
+The Node documentation is now split by module under `doc/unimplemented/node/`.
 
 > 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/requirements.md

@@ -46,6 +46,13 @@ Working around the limitation by compiling the IR elsewhere is not supported.
 The Windows release targets the **MSVC ABI**: clang uses the
 Windows SDK and the MSVC C/C++ runtime/headers.
 
+Optional optimization features add two tools:
+
+- `--lto` needs **lld** (`-fuse-ld=lld`); the LLVM installs above include it.
+- `--pgo-use` needs **llvm-profdata** to merge `.profraw` files. The driver
+  prefers the copy next to the resolved clang; override it with
+  `xbintsc_LLVM_PROFDATA`.
+
 ## Prebuilt releases (recommended)
 
 Download the archive for your platform from
@@ -114,9 +121,10 @@ 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
+## Windows — install the MSVC C++ build tools (and LLVM)
 
-Install LLVM and the Visual Studio C++ build tools with `winget`:
+xbintsc targets the **MSVC ABI** on Windows. Install the Visual Studio C++
+build tools plus LLVM with `winget`:
 
 ```powershell
 winget install -e --id LLVM.LLVM
@@ -124,17 +132,24 @@ 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:
+The LLVM bundled with Visual Studio 2022
+(`VC\Tools\Llvm\x64\bin\clang.exe`, version 19.1.5 in current installs) is
+enough, and so is a standalone LLVM. Either way the compiler must target the
+MSVC ABI (`Target: *-windows-msvc`): clang built for another Windows ABI cannot
+link with the MSVC runtime, so `xbintsc` rejects it with an explicit error.
+
+A developer prompt is normally **not** required: `xbintsc` resolves the Visual
+Studio LLVM by absolute path, and that clang locates the MSVC/SDK headers,
+libraries and linker itself. If your installation still needs the environment
+imported, run the build from an **x64 Native Tools Command Prompt for VS 2022**
+(or **ARM64 Native Tools** on Windows on ARM), or import it manually:
 
 ```powershell
 & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
 ```
 
-Verify with `clang --version` (chocolatey also works: `choco install llvm`).
+Verify with `xbintsc doctor` (or `clang --version`); the report names the
+resolved compiler, its version and its target.
 
 ## Building from source (contributors only)
 

package/doc/unimplemented/classes.md

@@ -0,0 +1,22 @@
+# Classes and object orientation
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/classes.md)
+
+| 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 [Runtime deviations](./deviations.md)) |
+| 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) |

package/doc/unimplemented/deviations.md

@@ -0,0 +1,27 @@
+# Runtime deviations
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/deviations.md)
+
+These features **compile and run**, but the result does not fully match ECMAScript:
+
+| Item | Deviation |
+| --- | --- |
+| 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` | Not implemented |
+| First-class built-in methods | Implemented as unbound method values (see [Functions](./functions.md)); `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` | Real suspension on a stackful coroutine; `await` always queues a microtask (non-promises and already-settled promises included), so interleaving with pending `.then` callbacks matches the specification. Top-level `await` blocks on the event loop rather than yielding the module body. `fs/promises` and `fetch` offload their blocking work to a four-worker pool and settle on the reactor. Async generators suspend at both `await` and `yield`; `for await...of` awaits one step per iteration |
+| Async generator cleanup | `for await...of` does not call the iterator's `return()` when the loop exits early. `yield*` inside an async generator delegates to synchronous iterables only. `.return()` at a suspended `yield` completes without running `finally` (the same limitation as synchronous generators) |
+| `super` | `super.x` / `super(...)` takes the prototype of `this`'s prototype; single-level inheritance is correct, but depth > 1 may be inaccurate |
+| `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 [Module system](./modules.md)) |
+| `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
+> been brought in line with Node and are covered by the differential tests, so
+> they are no longer listed as deviations.

package/doc/unimplemented/expressions.md

@@ -0,0 +1,26 @@
+# Expressions and operators
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/expressions.md)
+
+## 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. `async function*` and `for await...of` are implemented: the body
+> may suspend at both `await` and `yield`, and every `.next()` returns a
+> promise. `import.meta` exposes `url`, `dirname` and `filename`, resolved from
+> the running executable's path (see [Module system](./modules.md)).
+
+## Not supported by the parser
+
+None known at the expression level.
+
+## Unimplemented operators
+
+| Operator | Status | Notes |
+| --- | --- | --- |
+| `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`) |

package/doc/unimplemented/functions.md

@@ -0,0 +1,21 @@
+# Functions
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/functions.md)
+
+| 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 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 function*`, `for await...of` and `Symbol.asyncIterator` are 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 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 |

package/doc/unimplemented/modules.md

@@ -0,0 +1,22 @@
+# Module system
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/modules.md)
+
+| 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.
+
+The implemented side of this contract is in [Module system](../implemented/modules.md).

package/doc/unimplemented/node/async.md

@@ -0,0 +1,20 @@
+# Async and the event-loop model
+
+> Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/async.md)
+
+Implemented:
+
+- Core event loop `runtime/xt_loop.c` (a `select(2)` reactor); `net` / `dgram` / `http` are all built on it.
+- Async I/O offload `runtime/xt_async_io.c`: blocking file and HTTP-client work runs on four worker threads and completes on the reactor, so `fs/promises` and `fetch` do not stall timers or sockets.
+- `Promise`, `async` / `await` are available (see the core documents); `fs/promises` returns Promises that settle from the reactor.
+- 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:
+
+- Node's `Timeout` object (`setTimeout` returns a numeric id; `setImmediate` and `queueMicrotask` exist as globals).
+- File watching: `fs.watch` / `fs/promises.watch` return inert objects; there is no inotify/kqueue/ReadDirectoryChangesW backend.
+- `Dir.read` / `Dir.close` invoke their callbacks immediately, and callback-style `fs.readFile` / `fs.writeFile` / … are still unsupported (use `fs/promises` or the `*Sync` forms).
+- 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 still a blocking `connect(2)` performed before the socket joins the reactor; HTTP responses require `Connection: close`, with no keep-alive / chunked transfer / pipelining. `fetch` has no TLS and buffers the whole body before resolving.
+- The offload pool is fixed at four workers; there is no thread-pool sizing option and no `AbortSignal` cancellation for queued jobs.

package/doc/unimplemented/node/bun.md

@@ -0,0 +1,9 @@
+# The Bun extension
+
+> Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/bun.md)
+
+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).

package/doc/unimplemented/node/fs-promises.md

@@ -0,0 +1,20 @@
+# `fs/promises` gaps
+
+> Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/fs-promises.md)
+
+`fs/promises` now offloads its blocking I/O to the async I/O pool (the
+implemented surface is in
+[implemented: `fs/promises`](../../implemented/node/fs-promises.md)); the
+remaining differences are behavioural:
+
+- `FileHandle.appendFile` behaves like `writeFile` (it writes at the current
+  file position instead of appending).
+- `FileHandle.readFile()` reads from the current file-descriptor offset.
+- `Dir.read` / `Dir.close` (sync and promise forms) complete their callbacks
+  immediately; `Dir.readSync` / `closeSync` remain synchronous.
+- `watch` resolves to the same never-emitting watcher as `fs.watch`; there is no
+  real file-watching backend.
+- Reads and writes are whole-file/one-shot operations; there are no streaming
+  `FileHandle` variants and no `AbortSignal` cancellation.
+- The pool has four workers; very many simultaneous operations queue behind
+  them (they still do not block the event loop).

package/doc/unimplemented/node/fs.md

@@ -0,0 +1,30 @@
+# `fs`
+
+> Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/fs.md)
+
+`fs` implements the **synchronous** API surface (files, directories,
+descriptors, metadata, links, `cp`, `glob`, `Dir`, `constants`), and
+`fs/promises` runs every file/descriptor operation on the asynchronous I/O pool
+(see [implemented: `fs`](../../implemented/node/fs.md) and
+[implemented: `fs/promises`](../../implemented/node/fs-promises.md)). What is
+still missing is mostly about APIs that need a different backend or callback
+plumbing:
+
+| 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 |
+
+## 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)` complete **synchronously** (the callback is invoked immediately); `FileHandle` methods do return real promises now.
+- `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.

package/doc/unimplemented/node/globals.md

@@ -0,0 +1,23 @@
+# Global objects and namespaces
+
+> Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/globals.md)
+
+| 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.

package/doc/unimplemented/node/modules.md

@@ -0,0 +1,21 @@
+# Fully unimplemented modules
+
+> Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/modules.md)
+
+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
+[implemented: Node extension](../../implemented/node.md)):
+
+| Module | Notes |
+| --- | --- |
+| `https` | TLS version of HTTP |
+| `readline` | command-line reading |
+| `tls` / `cluster` / `vm` | other core 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.

package/doc/unimplemented/node.md

@@ -0,0 +1,21 @@
+# Node extension: unimplemented
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/node.md)
+
+The Node extension implements 21 modules plus the event-loop integration; the
+implemented surface is documented page by page under
+[Node extension: implemented](../implemented/node.md). This section records what
+is missing or differs from Node.
+
+## Contents
+
+- [`fs`](./node/fs.md) — callback-style async operations, real file watching, option callbacks
+- [`fs/promises`](./node/fs-promises.md) — `FileHandle` append/read offsets, immediate `Dir` callbacks, inert `watch`, no cancellation
+- [Fully unimplemented modules](./node/modules.md) — `https`, `readline`, `tls`, `cluster`, `vm`, ...
+- [Global objects and namespaces](./node/globals.md) — `global`, `__dirname`, `require` outside `node_modules`
+- [Async and the event-loop model](./node/async.md) — blocked file watching, blocking `net.connect`, no keep-alive, fixed-size offload pool
+- [The Bun extension](./node/bun.md) — design example only
+
+A module's implemented page links to its limitation page; when a limitation is
+lifted, move the entry to the matching page under
+`../implemented/node/`.

package/doc/unimplemented/statements.md

@@ -0,0 +1,18 @@
+# Statements
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/statements.md)
+
+## 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.
+
+## 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).

package/doc/unimplemented/stdlib.md

@@ -0,0 +1,54 @@
+# Standard library
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/stdlib.md)
+
+## 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`
+
+## 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`)
+- 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`
+
+## 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` | ✓ arrays, objects, Map, Set, Date, RegExp and typed arrays (cycles and shared references preserved); functions, symbols, promises and generators are rejected |
+| `JSON.stringify` options | ✓ `space` (number/string, clamped to 10), a function/array `replacer`, and `toJSON` are honored |
+| 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 and microtasks | ✓ `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` / `setImmediate` / `clearImmediate` / `queueMicrotask` and `performance.now` (numeric ids, no `Timeout` / `Immediate` object). 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`) |
+
+## 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 view over the same buffer; `slice` copies |
+| `keys` / `values` / `entries` | ~ return arrays, not iterator objects |
+| `ArrayBuffer` / `DataView` / `.buffer` / `.byteOffset` semantics | ✓ `ArrayBuffer` (`slice`, `isView`), `DataView` (big-endian by default, `littleEndian` option), typed arrays backed by a buffer and exposing `.buffer` / `.byteOffset`; `new X(buffer, offset, length)` creates views |
+| `BigInt64Array` / `BigUint64Array` | ✗ not implemented |
+| `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` | ✓ typed arrays and `DataView` share the `ArrayBuffer` bytes; `Buffer`-backed typed-array views are still not implemented |

package/doc/unimplemented/toolchain.md

@@ -0,0 +1,14 @@
+# Toolchain, platform and engineering
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/toolchain.md)
+
+| Item | Status |
+| --- | --- |
+| GC (garbage collection) | ✓ non-moving mark-sweep in `xt_alloc.c`, armed by a live-heap threshold (`XT_GC_THRESHOLD` pins it) or `xt_gc_collect()`; after each collection the threshold becomes twice the surviving heap (floor 1 MiB), so the resident set follows the live set instead of only growing. `XT_GC_TRACE=1` prints one line per collection to stderr. Explicit roots + root providers + conservative active-stack scan. `WeakMap`/`WeakSet` keys are ephemerons (a value is retained only while its key is reachable) and `WeakRef` targets are cleared when unreachable; because the stack scan is conservative, a stale stack word can delay that clearing. No compaction 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` / `structuredClone` implemented; String.normalize missing |
+| Multi-file module bundling | partial: relative-path `.ts` bundling, ESM `node_modules` packages, namespace imports and bare-specifier extension module imports implemented; CommonJS is handled only inside `node_modules`; circular dependencies / live bindings are not implemented |
+| Real async runtime | ✓ `async`/`await` suspends on pending promises on the `select(2)` reactor: timers, TCP sockets, offloaded file/HTTP work and promise callbacks resume the coroutine. Still missing: real OS-level file watching, non-blocking `net.connect`, TLS for `fetch`, and user-visible worker threads (`worker_threads` uses 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 [Runtime deviations](./deviations.md) |

package/doc/unimplemented/types.md

@@ -0,0 +1,12 @@
+# Type system
+
+> Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/types.md)
+
+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).