xbintsc 0.5.6 → 0.5.21

package/dist/tests/version.test.js

@@ -7,9 +7,13 @@ describe("compiler version", () => {
         expect(COMPILER_VERSION).toBe(packageJson.version);
     });
     it("is part of the incremental cache key", () => {
-        const source = readFileSync(new URL("../src/driver/compiler.ts", import.meta.url), "utf8");
+        const source = readFileSync(new URL("../src/driver/build-key.ts", import.meta.url), "utf8");
         expect(source).toMatch(/hashParts\(\[\s*COMPILER_VERSION,/);
     });
+    it("keeps the version declaration out of compiler.ts", () => {
+        const source = readFileSync(new URL("../src/driver/compiler.ts", import.meta.url), "utf8");
+        expect(source).not.toMatch(/export const COMPILER_VERSION =/);
+    });
     it("is printed by `xbintsc version`", async () => {
         const { run } = await import("../src/cli/main.js");
         const lines = [];

package/dist/tests/version.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.test.js","sourceRoot":"","sources":["../../tests/version.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC3C,CAAC;AAEzB,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QAC3F,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,mCAAmC,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACnD,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,EAAE;YAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAClC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;SACnC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"version.test.js","sourceRoot":"","sources":["../../tests/version.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC3C,CAAC;AAEzB,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,GAAG,CAAC,4BAA4B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QAC5F,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,mCAAmC,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QAC3F,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,iCAAiC,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACnD,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,EAAE;YAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAClC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;SACnC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/doc/ai/README.md

@@ -33,9 +33,10 @@ the rules for changing the compiler.
 2. **Types are erased, never checked.** Annotations, interfaces, generics,
    `as`/`satisfies` and non-null `!` have no runtime effect, and no type checker
    runs. Only real runtime behaviour matters.
-3. **Node compatibility is opt-in and incomplete.** Node modules come from the
-   `node` extension (`--ext node`); bare third-party npm imports are not
-   supported.
+3. **Node compatibility is opt-in and incomplete.** Node built-ins come from the
+   `node` extension (`--ext node`). Packages under `node_modules` are resolved
+   and bundled at build time (ESM and CommonJS); there is no runtime package
+   lookup and circular dependencies are rejected.
 
 ## Choose your command
 

package/doc/ai/cli.md

@@ -10,14 +10,26 @@ the help text leaves implicit.
 | --- | --- | --- |
 | `xbintsc build <file.ts>` | Compile to `exe` (default), `obj` or `ir` | yes, except `--emit ir` |
 | `xbintsc run <file.ts> [-- args]` | Compile to an executable and execute it | yes (`--emit exe` only) |
+| `xbintsc watch <file.ts>` | Rebuild whenever the source tree changes (Ctrl+C to stop) | yes |
 | `xbintsc emit <file.ts>` | Print LLVM IR to stdout, write nothing | no |
+| `xbintsc check <file.ts>` | Front-end check (syntax, imports, supported subset); writes nothing | no |
 | `xbintsc doctor` | Report the resolved toolchain, runtime and icon tools | only for the probe |
 | `xbintsc version` | Print the version | no |
 | `xbintsc help` | Print the help text | no |
 
+`check` is not a type checker: annotations are erased, so a program that passes
+`check` can still fail at runtime. It catches syntax errors, unresolved imports
+and constructs outside the supported subset, which makes it a fast pre-commit
+or editor gate.
+
 Any command also accepts `--help`, which prints the help text and exits 0. An
 unknown command prints an error plus the help text and exits 1.
 
+`watch` polls the entry file's directory (build output, `dist`, `coverage` and
+`node_modules` are ignored) and re-runs `build` on every change. It accepts the
+same options as `build`; package sources under `node_modules` are not watched,
+so restart it after installing a dependency.
+
 ## Options
 
 ```
@@ -38,8 +50,33 @@ unknown command prints an error plus the help text and exits 1.
     --verbose         Print progress information
     --time            Print per-phase build timings
     --debug           Emit debug info (DWARF/CodeView) and keep frame pointers
+    --lto             Compile program and runtime to LTO bitcode; link with lld
+    --pgo-generate [dir]  Build an instrumented binary writing profiles to dir
+    --pgo-use [dir]   Build with the profiles collected from --pgo-generate
+    --json            Print diagnostics as a JSON array on stdout
+```
+
+### LTO and PGO
+
+`--lto` compiles the generated IR and the C runtime to LLVM bitcode (`-flto`)
+and links with lld (`-fuse-ld=lld`), so LLVM can optimize across the
+language/runtime boundary. lld must be installed alongside clang.
+
+PGO is a two-build workflow:
+
+```bash
+xbintsc build app.ts --pgo-generate=profiles   # instrumented binary
+./build/app                                    # run a representative workload
+xbintsc build app.ts --pgo-use=profiles        # optimized rebuild
 ```
 
+`--pgo-use` merges the `.profraw` files with `llvm-profdata` (the copy next to
+clang is preferred; override with `xbintsc_LLVM_PROFDATA`) and passes
+`-fprofile-use=<dir>` to clang. The profile directory defaults to
+`<outDir>/pgo`. LTO and PGO can be combined. A `--pgo-use` build is never served
+from the incremental cache, because the profile data can change independently
+of the source.
+
 Parsing details that occasionally surprise:
 
 - `--flag=value` and `--flag value` are both accepted.
@@ -67,6 +104,9 @@ matching field. `--no-config` skips discovery entirely.
 | `outDir` | string | Output directory (default `build/`) |
 | `output` | string | Explicit output path, overriding `outDir` |
 | `optimize` | `"0"｜"1"｜"2"｜"3"` | Optimization level |
+| `lto` | boolean | Compile program and runtime to LTO bitcode and link with lld |
+| `pgo` | `"generate"｜"use"` | Profile-guided optimization stage |
+| `pgoDir` | string | Profile directory (default `<outDir>/pgo`) |
 | `extensions` | string[] | Bundled extensions to enable, e.g. `["node"]` |
 | `extNative` | string[] | Native extension manifest paths |
 | `force` | boolean | Ignore the incremental cache |
@@ -82,6 +122,7 @@ unreadable or malformed config fails the build with `invalid JSON` or
 | --- | --- |
 | `xbintsc_CLANG` | Use this clang instead of resolving one from `PATH` |
 | `xbintsc_LINKER_ARGS` | Extra linker flags (e.g. `-fuse-ld=lld`) |
+| `xbintsc_LLVM_PROFDATA` | `llvm-profdata` used to merge PGO `.profraw` files |
 | `xbintsc_CACHE_DIR` | Object-cache directory (default: `.xbintsc`) |
 | `xbintsc_PREFER_PREBUILT` | `0` forces the runtime to be compiled from source |
 | `xbintsc_BINARY` | Native compiler binary the `bin/` launcher should run |

package/doc/ai/contributing.md

@@ -18,16 +18,12 @@ toolchain is required for anything that links a binary (see
 [troubleshooting.md](./troubleshooting.md)). `xbintsc emit` needs neither clang
 nor the runtime library, which makes it the fastest inner loop.
 
-Optional but recommended — install the repository hook:
-
-```bash
-git config core.hooksPath .githooks
-```
-
-`.githooks/pre-commit` **bumps the patch version on every commit** and folds
-`package.json` + `package-lock.json` into that commit (`npm version patch
---no-git-tag-version`). Expect a version bump in your commits; do not countermand
-it. Release tags are created by `release.yml`, never by the hook.
+Optional: install the repository hook with `git config core.hooksPath .githooks`.
+It bumps the patch version **only on `main`/`master`** — `package.json`,
+`package-lock.json` and `src/driver/version.ts` together. Feature branches never
+touch those files, which is what keeps two feature branches from conflicting on
+the version lines; do not bump the version on a feature branch. Release tags are
+created by `release.yml`, never by the hook.
 
 ## The test suites
 
@@ -80,7 +76,7 @@ mean the same thing in every generation. A compiled string stores UTF-8 bytes
 but indexes them in UTF-16 code units, so the self-hosted `readFileSync`
 (`--ext node`) hands the scanner a byte string (one byte per code unit, all
 `<= 0xFF`), while Node hands it the same file already decoded — read source
-files through `decodeUtf8` ([src/diagnostics/utf8.ts](../../src/diagnostics/utf8.ts))
+files through `sourceTextBytes` ([src/diagnostics/source-text.ts](../../src/diagnostics/source-text.ts))
 and never assume a code unit is a byte or a character. Getting this wrong shows
 up as a non-ASCII literal (`—` in a hint string) coming out re-encoded in
 `gen2.ll`, which is why the emitted IR is compared byte-for-byte rather than
@@ -114,7 +110,8 @@ diff scratch/ref.ll scratch/gen2.ll
   therefore never allocate per access.
 - The GC is a non-moving mark-sweep collector: new heap objects go through
   `xt_alloc`, and a value must be reachable from an explicit root slot, a
-  registered root provider (the event loop, the microtask queue) or the
+  registered root provider (the event loop, the microtask queue, the async I/O
+  job roots) or the
   conservative C-stack scan while it is live. A value held only in a C local that
   is not on the scanned stack is a bug.
 
@@ -131,7 +128,7 @@ npm run runtime:clean      # drop build/runtime-obj and runtime/lib
 ```
 
 Add a new C file only together with the place that lists the runtime sources
-(`RUNTIME_SOURCES` in [../../src/driver/compiler.ts](../../src/driver/compiler.ts)),
+(`RUNTIME_SOURCES` in [../../src/driver/runtime-objects.ts](../../src/driver/runtime-objects.ts)),
 because that list decides what gets compiled and linked. Extension C sources are
 declared by the extension itself.
 
@@ -177,13 +174,20 @@ A feature is not done until the docs match:
 
 | Document | Update when |
 | --- | --- |
-| [../implemented.md](../implemented.md) | a feature starts working |
-| [../unimplemented.md](../unimplemented.md) | a limitation appears or is lifted |
-| [../node-implemented.md](../node-implemented.md) / [../node-unimplemented.md](../node-unimplemented.md) | Node module coverage changes |
+| [../implemented/](../implemented/) — the page that owns the feature | a feature starts working |
+| [../unimplemented/](../unimplemented/) — the page that owns the limitation | a limitation appears or is lifted |
+| [../implemented.md](../implemented.md) / [../unimplemented.md](../unimplemented.md) | a whole new page is added (link it from the index) |
+| [../implemented/node.md](../implemented/node.md) / [../unimplemented/node.md](../unimplemented/node.md) | Node module coverage changes |
 | [language-support.md](./language-support.md) | the AI-facing summary of the above changes |
 | [../requirements.md](../requirements.md) | the toolchain or platform requirements change |
 | [cli.md](./cli.md) | a flag, config field or environment variable changes |
 
+Each feature area owns one small page, so a feature branch edits the page for
+its area (and the page's Chinese translation) instead of a monolith. The index
+page's "Where does a change belong?" table maps a change to its page. A test
+(`tests/docs/structure.test.ts`) checks that every English page has a Chinese
+counterpart and is linked from its index.
+
 Keep the Chinese translation (`doc/zh-CN/`, `doc/ai/zh-CN/`) in step with the
 English source; a half-translated page is worse than none because it silently
 goes stale.

package/doc/ai/extensions.md

@@ -36,7 +36,7 @@ resolve to the same implementation.
 | Module | Notes |
 | --- | --- |
 | `fs` | **synchronous API only** (`readFileSync`, `writeFileSync`, …); `fs/promises` is separate |
-| `fs/promises` | promise-based file APIs |
+| `fs/promises` | promise-based file APIs; the blocking I/O runs on the async I/O worker pool and settles on the reactor |
 | `path` | also hooks namespace dispatch, so `path.join(...)` works |
 | `os` | |
 | `process` | `process.cwd()`, `argv`, `env`, …; namespace dispatch too |
@@ -50,12 +50,13 @@ resolve to the same implementation.
 | `util`, `querystring`, `url`, `assert`, `test`, `zlib` | |
 
 Coverage per module (exact functions and options) is in
-[../node-implemented.md](../node-implemented.md); what is missing is in
-[../node-unimplemented.md](../node-unimplemented.md).
+[../implemented/node.md](../implemented/node.md); what is missing is in
+[../unimplemented/node.md](../unimplemented/node.md).
 
 Remember the runtime model before building on `net`/`http`: the event loop runs
-**after** the program body, but `async`/`await` now suspends on pending promises,
-so a promise settled from a socket callback can be awaited. See
+**after** the program body, but `async`/`await` suspends on pending promises, so a
+promise settled from a socket callback, a timer or an offloaded file/HTTP job can
+be awaited. `net.connect` itself is still blocking. See
 [language-support.md](./language-support.md).
 
 ### `gui` — HTML/CSS window
@@ -93,9 +94,11 @@ its limits.
 ## Third-party npm packages
 
 Bare specifiers that no enabled extension claims are looked up in `node_modules`
-and bundled **as source**. A package that is not plain ESM TypeScript/JavaScript
-— or that relies on CommonJS, `require`, `__dirname`, or circular dependencies —
-will not work. `require()` is rejected with a hint to convert to `import`.
+and bundled **as source**, including CommonJS packages (the bundler gives them a
+synthetic `module`/`exports` and lowers their `require` calls). What does not
+work: dynamic `require(<expression>)`, packages that depend on Node globals such
+as `__dirname`, and circular dependencies. `require()` in your own source is
+rejected with a hint to convert to `import`.
 
 Practical consequence: for a Node program, enabling `--ext node` is usually the
 right answer; reach for an npm dependency only when you must.
@@ -141,8 +144,8 @@ they wrap the argument and value helpers. Key ABI facts: values are 64-bit
 NaN-boxed words; strings are **not** NUL-terminated, so pair `xt_string_data`
 with `xt_string_length_value`; the runtime never moves or frees memory it handed
 out. Build with the same clang/ABI that xbintsc resolves (`xbintsc doctor`
-prints it), and on Windows build inside an **x64/ARM64 Native Tools Command
-Prompt**.
+prints it). On Windows that must be an MSVC-targeting clang — normally the LLVM
+bundled with Visual Studio; a developer prompt is not required.
 
 Working projects to copy: [`examples/extensions/cpp`](../../examples/extensions/cpp)
 and [`examples/extensions/rust`](../../examples/extensions/rust); the full guide

package/doc/ai/language-support.md

@@ -6,8 +6,8 @@ what you can write; follow the links for exact wording.
 Canonical detail (always current, much longer):
 
 - [../implemented.md](../implemented.md) — everything that works, by compiler stage
-- [../unimplemented.md](../unimplemented.md) — unsupported syntax, deviations, quick reference
-- [../node-implemented.md](../node-implemented.md) / [../node-unimplemented.md](../node-unimplemented.md) — the Node extension
+- [../unimplemented.md](../unimplemented.md) — unsupported syntax and deviations, one page per area
+- [../implemented/node.md](../implemented/node.md) / [../unimplemented/node.md](../unimplemented/node.md) — the Node extension
 
 > Chinese: [../zh-CN/implemented.md](../zh-CN/implemented.md), [../zh-CN/unimplemented.md](../zh-CN/unimplemented.md)
 
@@ -63,7 +63,7 @@ Canonical detail (always current, much longer):
 | `#private` fields / methods / statics | ⚠️ | stored under a literal `#x` key; no access enforcement; parent/child name collisions may alias |
 | `enum` / `const enum` | ✅ | forward + reverse mapping |
 | `private` / `protected` / `public` / `readonly` / `abstract` / `implements` | — | erased, no access control |
-| Generators `function*`, `yield`, `yield*` | ✅ | `async` generators are not supported |
+| Generators `function*`, `yield`, `yield*` | ✅ | sync and `async function*`; `for await...of` and `Symbol.asyncIterator` |
 | `arguments` object | ✅ | implicit; arrows see their own parameters |
 | Argument-count validation | 🚫 | never checked, though `fn.length` reports declared arity |
 
@@ -71,11 +71,14 @@ Canonical detail (always current, much longer):
 
 | Feature | Status | Notes |
 | --- | --- | --- |
-| `async` / `await`, `Promise`, `Promise.all` | ✅ | real suspension: an `async` body runs on a stackful coroutine, and awaiting a **pending** promise pauses it until the promise settles. Awaiting an already-settled value still continues synchronously |
+| `async` / `await`, `Promise`, `Promise.all` | ✅ | real suspension: an `async` body runs on a stackful coroutine, and awaiting a **pending** promise pauses it until the promise settles. Every `await` yields once, so a settled value or non-promise is queued as a microtask like Node |
 | `setTimeout` and callbacks | ✅ | timers run on the core event loop; `await new Promise(r => setTimeout(r, ms))` works |
+| `queueMicrotask` / `setImmediate` / `performance.now` | ✅ | microtasks share the promise FIFO queue; `setImmediate` is a zero-delay timer with numeric ids; `performance.now` is monotonic fractional milliseconds |
 | Sockets / servers (`http`, `net`, `dgram`) | ✅ | callbacks run on the event loop and can settle a promise you await (`net` / `http` examples included in the tests) |
-| `fs/promises` | ⚠️ | awaitable, but each call performs its I/O synchronously before settling, so it does not yield while the I/O runs |
-| `async` generators, worker threads | 🚫 | `async function*` is rejected; workers are child processes |
+| `fs/promises` | ✅ | file, directory and `FileHandle` operations run on the async I/O worker pool and settle on the reactor, so timers and sockets keep running while they wait |
+| Global `fetch` | ✅ | HTTP/1.1 client whose connect/send/receive runs on the same worker pool; `await fetch(...)` yields and redirects are followed on the reactor. `http://` only (no TLS) and the body is buffered before resolving |
+| Worker threads | 🚫 | workers are child processes |
+| `async` generators | ✅ | suspend at `await` and `yield`; every `.next()` returns a promise; `for await...of` supported |
 
 ## Types: parsed, then erased
 
@@ -95,7 +98,7 @@ behaviour is checked. Write the runtime code you mean.
 
 ## Standard library
 
-Implemented: `Math`, `JSON`, `Date`, `RegExp`, `Map`, `Set`, `WeakMap`/`WeakSet`,
+Implemented: `Math`, `JSON`, `Date`, `RegExp`, `Map`, `Set`, `WeakMap`/`WeakSet`/`WeakRef`,
 `Symbol`, `Error` family, `BigInt`, `Array`/`String`/`Number`/`Object` methods,
 typed arrays, `String.prototype.match`/`split`/`replace` with capture groups,
 immutable array helpers (`toReversed`, `toSorted`, `toSpliced`, `with`), global
@@ -105,12 +108,13 @@ URI functions, first-class built-in constructors (`const A = Array; new A(...)`,
 
 | Missing or different | Status |
 | --- | --- |
-| `String.prototype.normalize`, `structuredClone` | 🚫 |
+| `String.prototype.normalize` | 🚫 |
+| `structuredClone` | ✅ arrays, objects, Map, Set, Date, RegExp and typed arrays |
 | `Error.stack` capture | ⚠️ function-level frames (name/file/line), no columns; generator bodies are omitted |
 | Global RegExp `lastIndex` | ⚠️ `test`/`exec` ignore it for `/g` and `/y` |
 | Sparse array holes, array out-of-bounds | ⚠️ holes are not tracked distinctly; out-of-bounds reads give `undefined` |
 
-See section 3 of [../unimplemented.md](../unimplemented.md) for the full list.
+See [Unimplemented: standard library](../unimplemented/stdlib.md) for the full list.
 
 ## Modules
 
@@ -120,9 +124,9 @@ See section 3 of [../unimplemented.md](../unimplemented.md) for the full list.
 | Relative multi-file bundling | ✅ | a `./helper.js` specifier resolves to `helper.ts` |
 | `import * as ns`, default and named imports | ✅ | |
 | Node built-in modules | ✅ | only with `--ext node` — see [extensions.md](./extensions.md) |
-| Bare third-party npm packages | 🚫 | `node_modules` ESM packages are bundled as source only when no extension claims the specifier |
-| `require()` / CommonJS | 🚫 | rejected with a hint to use `import` |
-| Circular dependencies | 🚫 | |
+| Bare third-party npm packages | ⚠️ | resolved from `node_modules` and bundled as source (ESM and CommonJS); no runtime lookup, circular dependencies rejected |
+| `require()` / CommonJS | ⚠️ | rejected in your own source with a hint to use `import`; CommonJS packages inside `node_modules` are bundled |
+| Circular dependencies | 🚫 | value imports only; `import type` / `export type` are erased and never form an edge |
 | Live bindings | ⚠️ | imports and namespace members are snapshots |
 | `__dirname`, `__filename` | 🚫 | use `import.meta.dirname` / `import.meta.filename` |
 
@@ -134,13 +138,14 @@ See section 3 of [../unimplemented.md](../unimplemented.md) for the full list.
 | RegExp Unicode matching | ⚠️ the engine is byte-oriented: a literal `中` still matches, but `.` and character classes consume one byte per repetition, and `\d`/`\w` stay ASCII. Match offsets (`match.index`, `search`, replacement callbacks) are reported in UTF-16 code units |
 | Number formatting and coercion | ✅ matches Node (`toFixed`, `toPrecision`, hex/octal/binary parsing) |
 | `BigInt` | ✅ implemented |
-| Garbage collection | ✅ non-moving mark-sweep; explicit roots plus a conservative C-stack scan; single-threaded and stop-the-world; no weak references |
+| Garbage collection | ✅ non-moving mark-sweep; explicit roots plus a conservative C-stack scan; single-threaded and stop-the-world. WeakMap/WeakSet keys use an ephemeron fixed point and WeakRef targets are cleared when unreachable; a stale conservative stack word can delay clearing |
 | Threads | 🚫 single-threaded; `worker_threads` exists in the Node extension only |
 
 ## Platform
 
 Builds target macOS, Linux and Windows on x64 and arm64. On Windows the target
-is the **MSVC ABI**, so clang needs the MSVC/SDK environment — see
+is the **MSVC ABI**, so the compiler must be an MSVC-targeting clang (the LLVM
+bundled with Visual Studio works) — see
 [../requirements.md](../requirements.md). clang **16 or newer** is required.
 
 ## Before you write a large program

package/doc/ai/troubleshooting.md

@@ -47,12 +47,12 @@ it in `xbintsc.config.json` so it is always on:
 xbintsc run app.ts --ext node
 ```
 
-### `module '<pkg>' is not supported: xbintsc can import built-in platform modules, relative '.ts' files and ESM packages under node_modules; CommonJS packages are not supported`
+### `module '<pkg>' is not supported: expected a Node built-in (with --ext node), a relative .ts/.js file, or a package in node_modules`
 
-A bare third-party import that nothing can link. Either the package is CommonJS
-(unsupported), or it is an ESM package that failed to bundle. Prefer a Node
-built-in from the `node` extension; see [extensions.md](./extensions.md) for
-what can actually be bundled.
+A bare import that neither the enabled extensions nor `node_modules` resolved.
+Check the package name and its `exports`/`main` map, or use a Node built-in from
+the `node` extension; see [extensions.md](./extensions.md) for what can be
+bundled.
 
 ### ``CommonJS `require()` is not supported``
 
@@ -98,8 +98,10 @@ clang itself failed. The thrown message includes the full clang command and its
 stderr — read the stderr, not just the first line. Frequent causes:
 
 - the toolchain is too old (see above);
-- on Windows, clang cannot find the MSVC/SDK headers or libraries because the
-  environment was not imported. Run from an **x64 Native Tools Command Prompt
+- on Windows, the resolved clang cannot find the MSVC/SDK headers or libraries.
+  `xbintsc doctor` shows the compiler and its target; prefer the LLVM bundled
+  with Visual Studio, which locates the SDK itself. If your installation still
+  needs the environment imported, run from an **x64 Native Tools Command Prompt
   for VS 2022** (or **ARM64 Native Tools** on Windows on ARM), or import it
   first:
   ```powershell
@@ -119,8 +121,8 @@ described in [../gui.md](../gui.md).
 ### `Icon file not found` / icon tools missing
 
 `--icon`/`app.icon` paths resolve against the config file's directory. On
-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.
+Windows, embedding a PE icon needs `llvm-rc` (ships with LLVM); `doctor` reports
+the resolved tool, and a missing one is only fatal when an icon was requested.
 
 ## Reading a stack trace
 

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

@@ -30,8 +30,9 @@ source.ts --词法分析--> tokens --语法分析--> AST --绑定--> 绑定后
 2. **类型全部被擦除，从不做类型检查。** 类型注解、接口、泛型、`as`/`satisfies`、
    非空断言 `!` 在运行时没有任何作用，也没有类型检查器会跑。只有真实的运行时
    行为才算数。
-3. **Node 兼容是可选且不完整的。** Node 模块由 `node` 扩展提供（`--ext node`）；
-   不支持直接 import 第三方 npm 包。
+3. **Node 兼容是可选且不完整的。** Node 内置模块由 `node` 扩展提供（`--ext node`）；
+   `node_modules` 里的 npm 包在构建期解析并打包（ESM 和 CommonJS 都支持）；
+   运行时没有包查找，循环依赖会被拒绝。
 
 ## 选一条命令
 

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

@@ -9,13 +9,22 @@
 | --- | --- | --- |
 | `xbintsc build <file.ts>` | 编译为 `exe`（默认）、`obj` 或 `ir` | 需要，`--emit ir` 除外 |
 | `xbintsc run <file.ts> [-- args]` | 编译成可执行文件并运行 | 需要（且只支持 `--emit exe`） |
+| `xbintsc watch <file.ts>` | 源码树变化时自动重新构建（Ctrl+C 退出） | 需要 |
 | `xbintsc emit <file.ts>` | 把 LLVM IR 打到 stdout，不写文件 | 不需要 |
+| `xbintsc check <file.ts>` | 前端检查（语法、导入、支持的子集），不写文件 | 不需要 |
 | `xbintsc doctor` | 报告解析到的工具链、运行时与图标工具 | 仅在探测时需要 |
 | `xbintsc version` | 打印版本 | 不需要 |
 | `xbintsc help` | 打印帮助文本 | 不需要 |
 
+`check` 不是类型检查器：类型注解会被擦除，所以通过 `check` 的程序仍可能在运行时出错。
+它能发现语法错误、无法解析的导入以及超出支持子集的写法，适合作为提交前或编辑器的快速门禁。
+
 任何命令加 `--help` 都会打印帮助并返回 0。未知命令会打印错误与帮助文本，返回 1。
 
+`watch` 轮询入口文件所在目录（忽略 build 输出、`dist`、`coverage` 与 `node_modules`），
+每次变化后重新执行 `build`；它接受与 `build` 相同的参数。`node_modules` 里的包源码
+不会被监视，安装依赖后请重启 watch。
+
 ## 参数
 
 ```
@@ -35,8 +44,30 @@
     --verbose         打印进度信息
     --time            打印各构建阶段耗时
     --debug           生成调试信息（DWARF/CodeView）并保留帧指针
+    --lto             程序与运行时编译为 LTO bitcode，并用 lld 链接
+    --pgo-generate [dir]  构建插桩二进制，把 profile 写入 dir
+    --pgo-use [dir]   使用 --pgo-generate 收集的 profile 重新构建
+    --json            把诊断以 JSON 数组打到 stdout
+```
+
+### LTO 与 PGO
+
+`--lto` 把生成的 IR 与 C 运行时都编译为 LLVM bitcode（`-flto`），并用 lld
+（`-fuse-ld=lld`）链接，让 LLVM 能跨语言/运行时边界优化。需要安装 lld。
+
+PGO 是两次构建的流程：
+
+```bash
+xbintsc build app.ts --pgo-generate=profiles   # 插桩二进制
+./build/app                                    # 运行代表性负载
+xbintsc build app.ts --pgo-use=profiles        # 使用 profile 重新构建
 ```
 
+`--pgo-use` 会用 `llvm-profdata` 合并 `.profraw`（优先 clang 旁边的副本，可用
+`xbintsc_LLVM_PROFDATA` 覆盖），并向 clang 传 `-fprofile-use=<dir>`。profile 目录默认
+为 `<outDir>/pgo`。LTO 与 PGO 可以同时使用。`--pgo-use` 构建不会命中增量缓存，因为
+profile 数据可能独立于源码变化。
+
 少数容易踩的解析细节：
 
 - `--flag=value` 与 `--flag value` 都支持。
@@ -56,6 +87,9 @@
 | `outDir` | string | 输出目录（默认 `build/`） |
 | `output` | string | 显式输出路径，覆盖 `outDir` |
 | `optimize` | `"0"｜"1"｜"2"｜"3"` | 优化级别 |
+| `lto` | boolean | 程序与运行时编译为 LTO bitcode，并用 lld 链接 |
+| `pgo` | `"generate"｜"use"` | 按 profile 优化的阶段 |
+| `pgoDir` | string | Profile 目录（默认 `<outDir>/pgo`） |
 | `extensions` | string[] | 开启的内置扩展，如 `["node"]` |
 | `extNative` | string[] | 原生扩展清单路径 |
 | `force` | boolean | 忽略增量缓存 |
@@ -70,6 +104,7 @@ JSON schema：[xbintsc.config.schema.json](../../xbintsc.config.schema.json)。
 | --- | --- |
 | `xbintsc_CLANG` | 指定 clang，替代从 `PATH` 解析 |
 | `xbintsc_LINKER_ARGS` | 额外链接参数（如 `-fuse-ld=lld`） |
+| `xbintsc_LLVM_PROFDATA` | 合并 PGO `.profraw` 所用的 `llvm-profdata` |
 | `xbintsc_CACHE_DIR` | 对象缓存目录（默认 `.xbintsc`） |
 | `xbintsc_PREFER_PREBUILT` | `0` 强制从源码编译运行时 |
 | `xbintsc_BINARY` | `bin/` 启动器应运行的原生编译器二进制 |

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

@@ -16,15 +16,11 @@ npm test                 # 单元测试 + 端到端测试
 （见 [troubleshooting.md](./troubleshooting.md)）。`xbintsc emit` 既不需要 clang 也不需要
 运行时库，因此它是最快的内循环。
 
-可选但推荐——安装仓库钩子：
-
-```bash
-git config core.hooksPath .githooks
-```
-
-`.githooks/pre-commit` **会在每次提交时把补丁版本号 +1**，并把 `package.json` 与
-`package-lock.json` 一起折进该提交（`npm version patch --no-git-tag-version`）。请预期
-你的提交里会带版本号变更，不要对抗它。发布标签由 `release.yml` 创建，钩子从不打标签。
+可选：安装仓库钩子 `git config core.hooksPath .githooks`。它只在
+`main`/`master` 上把补丁版本号 +1（同时更新 `package.json`、
+`package-lock.json` 与 `src/driver/version.ts`）。功能分支从不改动这些文件，
+这正是两个功能分支不会在版本行上冲突的原因；不要在功能分支上改版本号。
+发布标签由 `release.yml` 创建，钩子从不打标签。
 
 ## 测试套件
 
@@ -70,7 +66,7 @@ gen2 --emit--> gen3.ll      # 必须等于 ref.ll
 第二个推论是字符串模型：编译器自身源码文本在各代中必须含义一致。编译后的字符串以 UTF-8
 存储，但索引按 UTF-16 码元进行，所以自举后的 `readFileSync`（`--ext node`）交给扫描器的是
 字节串（一个码元一个字节，全部 `<= 0xFF`），而 Node 交给它的是同一个文件已解码后的文本——
-读取源码文件一律走 `decodeUtf8`（[src/diagnostics/utf8.ts](../../../src/diagnostics/utf8.ts)），
+读取源码文件一律走 `sourceTextBytes`（[src/diagnostics/source-text.ts](../../../src/diagnostics/source-text.ts)），
 不要假设一个码元就是一个字节或一个字符。弄错的表现是：`gen2.ll` 里非 ASCII 字面量（比如提示语里的 `—`）
 被重新编码，这也正是这里逐字节比较 IR 而不是逐行比较的原因。
 
@@ -97,7 +93,7 @@ diff scratch/ref.ll scratch/gen2.ll
 - 字符串字面量会被驻留：每个不同字面量只在 `main` 中创建一次，存入 GC 根全局，
   每次使用只做一次 load；属性名因此不再逐次分配。
 - GC 是非移动标记清扫：新堆对象走 `xt_alloc`；值存活期间必须能从显式根槽、已注册的
-  根提供者（事件循环、微任务队列）或 C 栈保守扫描到达。只存在于未被扫描的 C 局部
+  根提供者（事件循环、微任务队列、异步 I/O job 根）或 C 栈保守扫描到达。只存在于未被扫描的 C 局部
   变量里的值就是 bug。
 
 ## 修改运行时
@@ -111,7 +107,7 @@ npm run runtime            # tsx scripts/build-runtime.ts -> runtime/lib/<os>-<a
 npm run runtime:clean      # 删除 build/runtime-obj 与 runtime/lib
 ```
 
-新增 C 文件时必须同时更新列出运行时源文件的地方（[../../../src/driver/compiler.ts](../../../src/driver/compiler.ts)
+新增 C 文件时必须同时更新列出运行时源文件的地方（[../../../src/driver/runtime-objects.ts](../../../src/driver/runtime-objects.ts)
 里的 `RUNTIME_SOURCES`），因为那份列表决定什么会被编译和链接。扩展的 C 源由扩展自己声明。
 
 ## 新增或扩展一个扩展
@@ -153,13 +149,18 @@ src/extensions/node/fs/index.ts        runtime/ext_node/fs/read_file.c
 
 | 文档 | 何时更新 |
 | --- | --- |
-| [../../zh-CN/implemented.md](../../zh-CN/implemented.md) | 某特性开始可用 |
-| [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) | 出现或解除了某个限制 |
-| [../../zh-CN/node-implemented.md](../../zh-CN/node-implemented.md) / [../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md) | Node 模块覆盖变化 |
+| [../../zh-CN/implemented/](../../zh-CN/implemented/) 中拥有该功能的页面 | 某特性开始可用 |
+| [../../zh-CN/unimplemented/](../../zh-CN/unimplemented/) 中拥有该限制的页面 | 出现或解除了某个限制 |
+| [../../zh-CN/implemented.md](../../zh-CN/implemented.md) / [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) | 新增整页时（在索引里加链接） |
+| [../../zh-CN/implemented/node.md](../../zh-CN/implemented/node.md) / [../../zh-CN/unimplemented/node.md](../../zh-CN/unimplemented/node.md) | Node 模块覆盖变化 |
 | [language-support.md](./language-support.md) | 上述内容的 AI 摘要变化 |
 | [../../zh-CN/requirements.md](../../zh-CN/requirements.md) | 工具链或平台要求变化 |
 | [cli.md](./cli.md) | 参数、配置字段或环境变量变化 |
 
+每个功能域只拥有一个小页面，因此功能分支改自己领域的页面（以及它的中文翻译），
+而不是一份大文档。索引页的「改动应该写在哪一页？」表把改动映射到页面。
+`tests/docs/structure.test.ts` 会检查每个英文页面都有中文对应页，且都被索引链接。
+
 中文翻译（`doc/zh-CN/`、`doc/ai/zh-CN/`）要与英文源同步；半翻译的页面比没有更糟，因为
 它会静默过期。
 

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

@@ -35,7 +35,7 @@ xbintsc run app.ts --ext node
 | 模块 | 说明 |
 | --- | --- |
 | `fs` | **仅同步 API**（`readFileSync`、`writeFileSync` 等）；`fs/promises` 是独立模块 |
-| `fs/promises` | 基于 Promise 的文件 API |
+| `fs/promises` | 基于 Promise 的文件 API；阻塞 I/O 跑在异步 I/O 线程池上并在 reactor 上 settle |
 | `path` | 同时接入命名空间分发，`path.join(...)` 可用 |
 | `os` | |
 | `process` | `process.cwd()`、`argv`、`env` 等；也接入命名空间分发 |
@@ -49,12 +49,13 @@ xbintsc run app.ts --ext node
 | `util`、`querystring`、`url`、`assert`、`test`、`zlib` | |
 
 各模块的具体覆盖（确切函数与选项）见
-[../../zh-CN/node-implemented.md](../../zh-CN/node-implemented.md)，缺失项见
-[../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md)。
+[../../zh-CN/implemented/node.md](../../zh-CN/implemented/node.md)，缺失项见
+[../../zh-CN/unimplemented/node.md](../../zh-CN/unimplemented/node.md)。
 
 在 `net`/`http` 上搭东西之前，先记住运行时模型：事件循环在**程序主体之后**才运行，
-但 `async`/`await` 现在会在 pending Promise 上挂起，因此由套接字回调 settle 的 Promise
-可以被 await。见 [language-support.md](./language-support.md)。
+但 `async`/`await` 会在 pending Promise 上挂起，因此由套接字回调、定时器或 offload 的
+文件/HTTP job settle 的 Promise 都可以 await。`net.connect` 本身仍是阻塞的。见
+[language-support.md](./language-support.md)。
 
 ### `gui` —— HTML/CSS 窗口
 
@@ -82,9 +83,10 @@ Windows 唯一不支持的：Windows 的 `gui.a` 不构建 FFmpeg，媒体槽位
 
 ## 第三方 npm 包
 
-没有被已启用扩展认领的裸说明符，会在 `node_modules` 里查找并**作为源码**打包。不是
-纯 ESM TypeScript/JavaScript 的包——或依赖 CommonJS、`require`、`__dirname`、循环
-依赖的包——都不会工作。`require()` 会被拒绝并提示改用 `import`。
+没有被已启用扩展认领的裸说明符，会在 `node_modules` 里查找并**作为源码**打包，
+CommonJS 包也在支持范围内（打包器会给它合成 `module`/`exports`，并降级其中的
+`require` 调用）。不支持的场景：动态 `require(<表达式>)`、依赖 `__dirname` 等 Node
+全局变量的包，以及循环依赖。自己源码里的 `require()` 会被拒绝并提示改用 `import`。
 
 实践结论：写 Node 程序时，正确做法通常就是开 `--ext node`；只有确实必要时才去依赖
 npm 包。
@@ -127,7 +129,8 @@ xbintsc build demo.ts --ext-native a.json,b.json      # 多个
 与值的辅助函数。关键 ABI 事实：值是 64 位 NaN-boxed 字；字符串**不**以 NUL 结尾，
 所以要把 `xt_string_data` 与 `xt_string_length_value` 配对使用；运行时交给你的内存
 不会被移动或释放。请使用与 xbintsc 解析到的同一个 clang/ABI 构建（`xbintsc doctor`
-会打印它）；在 Windows 上要在 **x64/ARM64 Native Tools 命令提示符**里构建。
+会打印它）。Windows 上必须是面向 MSVC 的 clang，通常就是 Visual Studio 自带的
+LLVM；不需要开发者命令提示符。
 
 可直接照抄的工程：[`examples/extensions/cpp`](../../../examples/extensions/cpp) 与
 [`examples/extensions/rust`](../../../examples/extensions/rust)；完整指南见