xbintsc 0.5.6 → 0.5.21

package/doc/zh-CN/implemented/node/process.md

@@ -0,0 +1,23 @@
+# `process` 对象
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/process.md)
+
+实现位置：`src/extensions/node/process/index.ts`、`runtime/ext_node/process/process.c`
+
+方法调用降为 `xt_process_call(<name>, argc, argv)`，属性访问降为 `xt_process_get(<name>)`。
+通过 `import process from "process"` 导入后使用。
+
+| 方法 / 属性 | 说明 |
+| --- | --- |
+| `process.cwd()` | 当前工作目录 |
+| `process.exit([code])` | 退出进程 |
+| `process.uptime()` | 进程运行时间（秒） |
+| `process.hrtime()` | `[秒, 纳秒]` 数组 |
+| `process.getuid()` | 用户 ID（Windows 返回 0） |
+| `process.platform` / `process.arch` | 平台 / 架构 |
+| `process.pid` / `process.ppid` | 进程 ID / 父进程 ID |
+| `process.argv` | 参数数组（`argv[0]` 为可执行文件） |
+| `process.env` | 环境变量对象 |
+| `process.version` / `process.title` | 占位字符串 |
+
+> `argv` 由生成的 `main` 通过 `xt_set_program_args` 捕获后提供给运行时。

package/doc/zh-CN/implemented/node/querystring.md

@@ -0,0 +1,20 @@
+# `querystring` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/querystring.md)
+
+位置：`src/extensions/node/querystring/index.ts`、`runtime/ext_node/querystring/querystring.c`
+
+| 函数 | 说明 |
+| --- | --- |
+| `parse(str[, sep[, eq]])` / `decode` | 解析为对象；重复的键会变成数组 |
+| `stringify(obj[, sep[, eq]])` / `encode` | 序列化；空格变成 `+`，数组会重复键 |
+| `escape(str)` / `unescape(str)` | 百分号编码 / 解码（`+` 解码为空格） |
+
+默认值：`sep = "&"`，`eq = "="`。
+
+```ts
+import { parse, stringify } from "querystring";
+
+const q = parse("a=1&b=2&b=3");      // { a: "1", b: ["2", "3"] }
+console.log(stringify({ x: "a b" })); // x=a+b
+```

package/doc/zh-CN/implemented/node/stream-promises.md

@@ -0,0 +1,8 @@
+# `stream/promises` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/stream-promises.md)
+
+实现位置：`src/extensions/node/stream-promises/index.ts`、`runtime/ext_node/stream/pipeline.c`
+
+- `pipeline(...)` 同步排空给定流，并返回一个已 resolve 的 Promise，因此 `await pipeline(...)` 可用。
+- 支持的转换阶段为 `zlib.createGzip()`，见 [`zlib`](./zlib.md)。

package/doc/zh-CN/implemented/node/stream.md

@@ -0,0 +1,15 @@
+# `stream` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/stream.md)
+
+实现位置：`src/extensions/node/stream/index.ts`、`runtime/ext_node/stream/stream.c`
+
+`Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough` 作为**全局构造函数**使用（`new Readable()` 等）；`stream.Readable.from(...)` 等静态方法通过 `stream` 命名空间解析。流是 EventEmitter，采用**同步事件模型**：`on('data')` 时冲刷 `push` 缓冲，`write` 即时投递。
+
+| 方法 | 说明 |
+| --- | --- |
+| `push(chunk)` / `read([n])` | Readable 端 |
+| `write(chunk)` / `end([chunk])` | Writable 端 |
+| `pipe(destination)` | 数据转发 |
+| `on('data' / 'end' / 'finish')` | 事件 |
+| `pause()` / `resume()` / `setEncoding(enc)` / `destroy()` | 流控制 |

package/doc/zh-CN/implemented/node/test.md

@@ -0,0 +1,10 @@
+# `test` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/test.md)
+
+实现位置：`src/extensions/node/test/index.ts`、`runtime/ext_node/test/test.c`
+
+- `test(name, fn)` 立即执行 `fn`，捕获断言失败并输出 TAP。
+- `it` / `describe` / `skip` / `todo` / `only` 以及 `before` / `after` / `beforeEach` / `afterEach` 钩子。
+- 失败时进程以非零码退出。
+- 默认导出可调用，因此 `import test from "node:test"` 可用。

package/doc/zh-CN/implemented/node/url.md

@@ -0,0 +1,8 @@
+# `url` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/url.md)
+
+实现位置：`src/extensions/node/url/index.ts`、`runtime/ext_node/url/url.c`
+
+- `pathToFileURL(path)` 与 `fileURLToPath(url)`。
+- 这两个助手用于在 `import.meta.url`、`process.argv[1]` 与文件系统路径之间转换。

package/doc/zh-CN/implemented/node/util.md

@@ -0,0 +1,25 @@
+# `util` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/util.md)
+
+位置：`src/extensions/node/util/index.ts`、`runtime/ext_node/util/util.c`
+
+同时支持命名导入（`import { format } from "util"`）与命名空间调用
+（`import util from "util"` / `import * as util from "util"`）。
+
+| 函数 | 说明 |
+| --- | --- |
+| `format(fmt, ...args)` | 支持 `%s` `%d` `%i` `%f` `%j` `%o` `%O` `%c` `%%` 占位符 |
+| `formatWithOptions(opts, fmt, ...args)` | 接受选项但忽略 |
+| `inspect(value)` | 递归打印（限制深度，字符串带引号） |
+| `isDeepStrictEqual(a, b)` | 结构比较（`NaN` 等于 `NaN`） |
+| `inherits(ctor, superCtor)` | 连接原型链 |
+| `deprecate(fn, msg)` | 原样返回 `fn`（没有告警通道） |
+| `promisify(fn)` | 把「回调在末尾」的函数包装为 `Promise` |
+| `isString` `isNumber` `isBoolean` `isUndefined` `isNull` `isFunction` `isArray` `isObject` `isBuffer` `isDate` `isRegExp` `isPromise` `isError` | 类型判断 |
+
+```ts
+import { format, promisify } from "util";
+
+console.log(format("%s=%d", "n", 3)); // n=3
+```

package/doc/zh-CN/implemented/node/worker-threads.md

@@ -0,0 +1,9 @@
+# `worker_threads` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/worker-threads.md)
+
+实现位置：`src/extensions/node/worker_threads/index.ts`、`runtime/ext_node/worker_threads/worker_threads.c`
+
+- `Worker`、`isMainThread`、`workerData`、`parentPort`。
+- xbintsc 通过把当前可执行文件作为子进程重新运行来模拟 worker；`isMainThread` /
+  `workerData` / `parentPort` 是值绑定（无参运行时 getter），`Worker` 是构造器。

package/doc/zh-CN/implemented/node/zlib.md

@@ -0,0 +1,8 @@
+# `zlib` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/zlib.md)
+
+实现位置：`src/extensions/node/zlib/index.ts`、`runtime/ext_node/zlib/zlib.c`
+
+- 仅实现 `createGzip()`。它返回 gzip 转换流，供
+  [`stream/promises`](./stream-promises.md) 的 `pipeline` 使用。

package/doc/zh-CN/implemented/node.md

@@ -0,0 +1,45 @@
+# Node 扩展：已实现
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/node.md)
+
+实现位置：`src/extensions/node/`、`runtime/ext_node/`
+
+`node` 扩展是可选的：通过 `--ext node`（或 `xbintsc.config.json` 里的
+`"extensions": ["node"]`）启用。它是平台扩展：每个 Node 模块一个子目录，
+TypeScript 导出与 C 实现一一对应。新增模块不需要改动核心编译器；扩展契约见
+[扩展机制](./extensions.md)。
+
+每个模块有独立页面，改动一个模块不会和另一个模块的工作冲突。缺失或行为不同之处
+记录在[Node 扩展：未实现](../../unimplemented/node.md)。
+
+## 模块
+
+| 模块 | 页面 | 说明 |
+| --- | --- | --- |
+| `fs` | [fs](./node/fs.md) | 仅同步 API |
+| `fs/promises` | [fs/promises](./node/fs-promises.md) | 由 reactor 驱动、跑在异步 I/O 线程池上的文件与 `FileHandle` 操作 |
+| `path` | [path](./node/path.md) | `path.<name>(...)` 命名空间调用 |
+| `os` | [os](./node/os.md) | `os.<name>(...)` 命名空间调用 |
+| `process` | [process](./node/process.md) | 对象：方法与属性 |
+| `buffer` | [buffer](./node/buffer.md) | `Buffer` 以普通对象表示 |
+| `stream` | [stream](./node/stream.md) | `Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough` |
+| `stream/promises` | [stream/promises](./node/stream-promises.md) | 仅 `pipeline` |
+| `net` | [net](./node/net.md) | TCP 服务端与客户端 |
+| `dgram` | [dgram](./node/dgram.md) | UDP 套接字 |
+| `http` | [http](./node/http.md) | 服务端与客户端，`Connection: close` |
+| `child_process` | [child_process](./node/child-process.md) | 仅 `spawnSync` |
+| `events` | [events](./node/events.md) | `EventEmitter`（全局与具名导出） |
+| `util` | [util](./node/util.md) | 格式化、inspect 与类型谓词 |
+| `querystring` | [querystring](./node/querystring.md) | parse / stringify / escape |
+| `assert` | [assert](./node/assert.md) | 断言函数 |
+| `test` | [test](./node/test.md) | 最小 TAP 运行器 |
+| `crypto` | [crypto](./node/crypto.md) | `createHash`（SHA-1 / SHA-256） |
+| `url` | [url](./node/url.md) | `pathToFileURL` / `fileURLToPath` |
+| `zlib` | [zlib](./node/zlib.md) | 仅 `createGzip` |
+| `worker_threads` | [worker_threads](./node/worker-threads.md) | 以子进程模拟 |
+
+## 改动应该写在哪一页？
+
+Node 模块改动通常涉及 `src/extensions/node/<module>/` 与 `runtime/ext_node/<module>/`；
+文档写到 `node/<module>.md`，若改变了限制，再写到
+`../../unimplemented/node/` 下对应页面。核心编译器不需要改动。

package/doc/zh-CN/implemented/operators.md

@@ -0,0 +1,38 @@
+# 运算符与赋值
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/operators.md)
+
+实现位置：`src/codegen/llvm.ts`（`BINARY_RUNTIME`、`emitPrefix`、`emitPostfix`、`emitAssignment`）
+
+## 算术
+
+`+ - * / % **`（`**` 右结合）
+
+## 比较与相等
+
+`< <= > >=`、`== !=`（宽松相等）、`=== !==`（严格相等）
+
+## 逻辑与短路
+
+`&& || ??`（含短路求值）、`!`
+
+## 位运算
+
+`& | ^ ~ << >> >>>`
+
+## 一元
+
+`+ - ! ~`、前缀 / 后缀 `++ --`
+
+## 赋值
+
+`= += -= *= /= %= **= <<= >>= >>>= &= |= ^= &&= ||= ??=`
+
+## 其他表达式运算符
+
+- 逗号表达式 `,`
+- `in` 运算符（`key in obj`，映射 `xt_in`）
+- `delete obj.key` / `delete obj[key]`（映射 `xt_delete`）
+- `instanceof`（映射 `xt_instance_of`，沿原型链判断）
+
+> `typeof` / `void` 作为一元运算符已实现。

package/doc/zh-CN/implemented/parser.md

@@ -0,0 +1,58 @@
+# 语法分析（Parser）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/parser.md)
+
+实现位置：`src/parser/parser.ts`、`src/ast/nodes.ts`
+
+模块语法（`import` / `export`、import attributes）及其驱动层打包见[模块系统](./modules.md)。
+
+## 语句
+
+- 变量声明：`var` / `let` / `const`，支持多声明符 `const a = 1, b = 2;`
+- 函数声明、函数表达式和方法，含 `async` 修饰、生成器（`function*`、`yield`、`yield*`、`.next`/`.throw`/`.return`）与异步生成器（`async function*`、`for await...of`）
+- `class` 声明 / 类表达式（构造函数、字段、方法、`static`、`extends`）
+- `if` / `else`
+- `while`、`do...while`
+- `for`（初始化、条件、增量均可省略）
+- `for...of`、`for...in`
+- `return`、`break`、`continue`、`throw`（含带标签的 `break label` / `continue label`）
+- `switch` / `case` / `default`（含穿透 fall-through）
+- `try` / `catch` / `finally`（基于运行时 setjmp 帧的可捕获异常）
+- `export var` / `export let` / `export const`（修饰符解析后擦除）
+- 块语句 `{}`、空语句 `;`、`debugger;`
+- 表达式语句
+
+## 表达式
+
+- 全部常见运算符及优先级 / 结合性（见[运算符](./operators.md)）
+- 赋值表达式与全部复合赋值（见[运算符](./operators.md)）
+- 条件（三元）表达式 `a ? b : c`
+- 箭头函数 `() => expr` / `() => { ... }`（含类型参数、返回类型注解）
+- 函数表达式 `function () {}` 与命名函数表达式 `function g() {}`
+- 调用表达式 `f(...)`、成员访问 `a.b`、元素访问 `a[i]`
+- 数组字面量 `[1, 2]`、稀疏数组 elision、展开 `[...a]`（也支持字符串、`Map`、`Set`）
+- 对象字面量 `{ a: 1 }`、简写属性 `{ a }`、方法简写 `{ m() {} }`、getter/setter 简写 `{ get x() {} }` / `{ set x(v) {} }`、计算属性名 `{ [expr]: 1 }`、对象展开 `{ ...obj }`
+- 模板字面量 `${}` 替换、标记模板（含 raw 字符串与 `String.raw`）
+- 括号表达式、`as` / `satisfies` / 非空断言 `!`（类型擦除）
+- 一元：`+ - ! ~ typeof void`、前缀 / 后缀 `++ --`
+- 可选链 `?.` / `?.[]` / `?.()`（含空值短路语义）
+- `delete` 表达式（删除对象属性）
+
+## TypeScript 类型语法（仅解析、结构保留后擦除）
+
+- 类型注解、返回类型注解、类型参数 `<T>` 与约束 `<T extends U>`、类型参数默认值
+- 类型引用、限定名 `A.B`
+- 联合 `|`、交叉 `&`、数组 `T[]`、元组 `[T, U]`、可选元组成员 `T?`、剩余元组成员 `...T`
+- 函数类型 `(a: T) => U`、构造签名 `new () => T`
+- 对象类型字面量、属性签名、方法签名、索引签名 `[k: string]: T`
+- 条件类型 `T extends U ? X : Y`、映射类型 `{ [K in T]: U }`、`infer`
+- 类型运算符 `keyof`、`unique`、`readonly`
+- `typeof`（类型查询）、索引访问类型 `T[K]`
+- 字面量类型、`this` 类型
+- 类型谓词 `x is T` / `asserts x is T`
+- 接口、类型别名、枚举、命名空间 / 模块声明
+- `import` / `export` 的各种形式（结构解析）
+
+## ASI
+
+- 自动分号插入（Automatic Semicolon Insertion），依据 `precededByLineBreak` / `}` / EOF。

package/doc/zh-CN/implemented/pipeline.md

@@ -0,0 +1,25 @@
+# 编译流水线
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/pipeline.md)
+
+```
+source.ts
+   │  词法分析  src/lexer/scanner.ts + token.ts
+   ▼
+ tokens
+   │  语法分析  src/parser/parser.ts  →  AST  src/ast/
+   ▼
+ AST
+   │  名字绑定  src/binder/binder.ts  →  作用域/符号/闭包捕获
+   ▼
+ bound AST
+   │  代码生成  src/codegen/llvm.ts + values.ts  →  LLVM IR 文本
+   ▼
+ module.ll ── clang ──► module.o ──链接──► 可执行文件
+                                   ▲
+                          runtime/*.c（C 运行时，按功能拆分）
+```
+
+- 前端与后端、运行时、扩展完全解耦。
+- 流程由 `src/driver/compiler.ts` 串起：`读取 → 解析 → 绑定 → IR → 目标文件 → 链接`。前端位于 `src/driver/frontend.ts`，缓存键位于 `src/driver/build-key.ts`，运行时编译位于 `src/driver/runtime-objects.ts`，平台产物位于 `src/driver/app-artifacts.ts`。
+- **自举**：`xbintsc` 可编译自身前端。用编译器构建 `src/cli/main.ts` 可得到可用的 `xbintsc` 二进制，且该二进制再自编译时产出的 LLVM IR 逐字节一致（源码 ≡ 第 1 代 ≡ 第 2 代 ≡ 第 3 代）。运行时仍为手写 C。

package/doc/zh-CN/implemented/runtime-core.md

@@ -0,0 +1,31 @@
+# C 运行时核心
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/runtime-core.md)
+
+实现位置：`runtime/xt_alloc.c`、`runtime/xt_values.c`、`runtime/xt_containers.c`、
+`runtime/xt_builtins.c`、`runtime/xt_constructors.c`、`runtime/xt_io.c`，共享私有头
+`runtime/rt_internal.h`；公开 ABI 见 `runtime/rt.h`。
+
+字符串、symbol、类型化数组、集合、Promise/异步、`fetch` 与标准库表面各有独立页面：
+
+- [字符串与文本](./strings.md)
+- [标准库](./stdlib.md)
+- [集合](./collections.md)
+- [类型化数组与二进制数据](./typed-arrays.md)
+- [异步、Promise 与生成器](./async.md)
+- [fetch](./fetch.md)
+
+- 分配器：`xt_alloc` 背后的非移动标记-清扫回收器（显式根、子系统根提供者与保守 C 栈扫描）。
+- 值构造：`xt_undefined/xt_null/xt_bool/xt_number/xt_string_new/xt_string_from_cstr`。
+- 类型转换：`xt_truthy`、`xt_to_number`、`xt_to_string`、`xt_typeof`。
+- 算术：`add/sub/mul/div/mod/pow/neg/pos`。
+- 位运算：`and/or/xor/not/shl/shr/ushr`（含 `ToInt32` 语义）。
+- 比较：`lt/le/gt/ge`、宽松 / 严格相等、`not`、`is_nullish`。
+- 对象：线性属性列表，`object_new/get/set/has/keys/values/entries/assign/spread`。
+- 数组：`array_new/get/set/push/length/spread`；对 `arr.length` 赋值会截断 / 扩展（与 JS 一致）；`iter_length` / `iter_value` 为数组、字符串（按码点）、`Map`、`Set` 提供统一迭代视图。
+- 通用成员访问：`xt_get` / `xt_set`（对数组 / 对象 / 字符串分发）。
+- 运算符辅助：`xt_in`（`in`）、`xt_delete`（`delete`）、`xt_rest_args`（剩余参数 / `arguments`）。
+- Box：`box_new/get/set`（用于闭包捕获变量）。
+- 函数与闭包：`arg`、`closure_new/call/env/arity`。
+- 异常：`xt_try_enter` / `xt_try_exception` / `xt_try_leave` 维护 `_setjmp` 帧栈；`xt_throw` 在存在帧时长跳到最近 `try`，否则打印 `Uncaught ...` 后退出。codegen 还会维护一条影子调用栈（函数名、源文件、行号）：`Error.stack` 用它生成堆栈（见[标准库](./stdlib.md)），原生崩溃时致命信号处理器也会打印同一组帧。`--debug` 还会生成 `!DICompileUnit` / `!DISubprogram` / `!DILocation` 元数据，并用 `-g -fno-omit-frame-pointer` 编译，因此 gdb/lldb/WinDbg 可以把指令映射回源码行。
+- 对象 / 函数：`xt_object` 带原型链，`xt_function` 带属性包（静态成员与 `prototype`）；`xt_new`（实例化）、`xt_instance_of`（原型链）、`xt_object_freeze/is_frozen/from_entries`；`xt_constructors.c` 保存一等公民构造器缓存、构造器原型与静态值分派。

package/doc/zh-CN/implemented/stdlib.md

@@ -0,0 +1,76 @@
+# 标准库
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/stdlib.md)
+
+实现位置：`runtime/xt_stdlib.c`、`runtime/xt_stdlib2.c`、`runtime/xt_symbol.c`、
+`runtime/xt_builtins.c`、`runtime/xt_constructors.c`、`runtime/xt_io.c`、
+`runtime/xt_structured_clone.c`、`runtime/xt_url.c`。
+
+分发层为 `xt_call_method`（数组 / 字符串方法与对象上的函数属性）、`xt_math_call`
+（`Math.*` 与常量）以及各构造器的 `xt_*` 入口。集合与类型化数组有独立页面：
+[集合](./collections.md)、[类型化数组与二进制数据](./typed-arrays.md)。
+
+## 对象
+
+- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`，对象展开 `{...obj}`。
+- `Object.defineProperty` / `getOwnPropertyDescriptor(s)` —— 数据属性与访问器属性；属性标志会被报告，但后续写入/枚举尚未强制执行。
+- `Object.freeze` / `is_frozen` / `from_entries`、`Object.getPrototypeOf`。
+- `Object.prototype`：`hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`；`Object.getPrototypeOf({}) === Object.prototype`。
+- 一等公民内建构造器（`const A = Array`、`new A(...)`、`A.isArray`、`x instanceof A`）见[代码生成](./codegen.md)。
+
+## 数组
+
+- `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`
+- 不可变方法：`toReversed` / `toSorted` / `toSpliced` / `with`。
+- 静态：`Array.isArray` / `of` / `from`。
+- 默认 `sort` 稳定，并按字符串形式比较（与 Node 一致）；对 `arr.length` 赋值会截断 / 扩展数组。
+
+## 数字、BigInt 与 Math
+
+- 数字格式化与强制转换与 Node 一致：`toFixed` / `toPrecision` / `toExponential`、十六 / 八 / 二进制解析，以及完整的 `+` / 关系运算 `ToPrimitive` 规则。这些由差分测试覆盖。
+- `BigInt` 字面量与值：任意精度算术、位运算与移位、比较、`toString(radix)`、`BigInt()`、`BigInt.asIntN` / `BigInt.asUintN`。
+- `Math`：完整函数与常量。
+- `Number` 静态与 `Number()` 转换；`parseInt` / `parseFloat` / `isNaN` / `isFinite`。
+
+## JSON
+
+- `JSON.parse` 支持 `reviver`。
+- `JSON.stringify` 支持函数或数组 `replacer`、`toJSON`，以及 `space`（数字或字符串，最多 10 个单位）。`undefined` / 函数 / symbol 值遵循标准省略规则。
+- 对象键按插入序输出，整数键按数值排序；循环引用抛错。
+
+## Date
+
+- `Date` 基于 `gmtime_r`；`Date.parse` / `new Date(string)` 支持 ISO 8601 解析。
+
+## RegExp
+
+- `RegExp` 使用 POSIX ERE（`regcomp` / `regexec`）实现 `test` / `exec`；捕获组可经 `exec` / `match` / `replace` / `split` / `search` 使用。
+- 匹配按字节进行，且 `/g` / `/y` 的 `lastIndex` 不被读取 —— 见[运行时偏差](../unimplemented/deviations.md)。
+
+## Symbol
+
+- `Symbol(description)` 原始值（`XT_OBJECT_KIND_SYMBOL`）、13 个著名符号（`Symbol.iterator`、`Symbol.asyncIterator`、`Symbol.match` 等）、`Symbol.for` / `Symbol.keyFor` 全局注册表、`symbol.description` / `toString()` / `valueOf()`。
+- symbol 可作为属性键（`Object.getOwnPropertySymbols`，symbol 键的 `get`/`set`/`in`/`delete`），会被 `Object.keys` / `values` / `entries` / `for...in` / `JSON.stringify` 跳过，打印为 `Symbol(desc)`。
+
+## URLSearchParams
+
+- `URLSearchParams` 实现在 `runtime/xt_url.c`。
+
+## 错误
+
+- `Error` 家族：`Error`、`TypeError`、`RangeError`、`SyntaxError`、`ReferenceError`、`EvalError`、`URIError`、`AggregateError` —— 支持 `new`、`instanceof`、`extends`、`String(err)` / `err.toString()` 与 `.stack`。
+- `Promise.any` 以 `AggregateError` 作为 rejection。
+- `.stack` 仅含函数级帧（`at 名称 (文件:行)`），取自运行时影子调用栈；具体限制见[运行时偏差](../unimplemented/deviations.md)。
+
+## console
+
+- `xt_print` / `xt_println` / `xt_console_log` / `info` / `warn` / `error`；`info` / `log` 到 stdout，`warn` / `error` 到 stderr。
+- Node 风格 inspect：数组 `[ a, b ]`、对象 `{ k: v }`，感知 UTF-8，循环引用会被标记。
+- `dir` / `trace` / `assert` / `count` / `countReset` / `group` / `groupEnd` / `table` / `time` / `timeEnd` / `timeLog`。
+
+## 全局函数
+
+- `parseInt` `parseFloat` `isNaN` `isFinite` `Number` `String` `Boolean` `encodeURI` `decodeURI` `encodeURIComponent` `decodeURIComponent`。
+- `btoa` / `atob` base64 编解码（核心全局函数，并非 Node 扩展专属）。
+- `structuredClone`：数组、对象、`Map`、`Set`、`Date`、`RegExp` 与类型化数组，保留循环引用与共享引用；函数、symbol、Promise、生成器会被拒绝。
+- 定时器、`queueMicrotask` 与 `performance.now` 见[异步、Promise 与生成器](./async.md)；`fetch` 见 [fetch](./fetch.md)。

package/doc/zh-CN/implemented/strings.md

@@ -0,0 +1,27 @@
+# 字符串与文本
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/strings.md)
+
+实现位置：字符串值在核心运行时（`runtime/xt_values.c`）；方法表面由
+`runtime/xt_stdlib.c` / `xt_stdlib2.c` 分发；`TextEncoder` / `TextDecoder` 位于
+`runtime/xt_text_codec.c`。
+
+## 值模型
+
+- UTF-8 存储，对外呈现 JavaScript 的 UTF-16 视图：`length`、索引、`slice`、`indexOf`、`split`、`padStart`、`codePointAt` 按码元计数；`for...of` 与 `Array.from` 按码点计数；孤立代理项以 WTF-8 保存，并在拼接时重新组合。
+- 惰性 cons 节点拼接：首次观察时才扁平化，因此循环追加保持线性复杂度。
+- 相等比较、格式化数字转字符串。
+- `xt_string_length` 供 I/O 使用，返回字节数；`xt_string_utf16_length` 返回 JavaScript 长度。
+
+## 方法
+
+- `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`
+- `String.match` / `lastIndexOf` / 带 limit 的 `split`；正则捕获组可经 `match` / `replace` / `split` / `search` 使用（见[标准库](./stdlib.md)）。
+- `String` 静态：`fromCharCode` / `fromCodePoint` / `raw`；标记模板保留 raw 字符串。
+
+## 文本编码
+
+- `TextEncoder` / `TextDecoder` 通过 `Uint8Array` 做编解码；仅支持 UTF-8。
+
+已知偏差（`String.prototype.normalize`、正则按字节匹配）见
+[未实现：标准库](../unimplemented/stdlib.md)。

package/doc/zh-CN/implemented/tests.md

@@ -0,0 +1,10 @@
+# 测试
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/tests.md)
+
+实现位置：`tests/`（`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`）
+
+- 各模块单元测试与源码树一一对应。
+- `tests/e2e/` 会真正编译并运行二进制；缺少 `clang` 时自动跳过，而不是静默通过。
+- `tests/e2e/differential-*.test.ts` 让同一份源码同时经 `xbintsc` 与 Node 运行并逐字节比较输出。语义变化时应新增差分用例，而不是手写期望字符串。
+- 本目录的各功能页记录受支持的行为，测试是这份契约的可执行形式。提交前的门禁（`npm run typecheck && npm run lint && npm test`）见[参与贡献](../../ai/contributing.md)。

package/doc/zh-CN/implemented/typed-arrays.md

@@ -0,0 +1,26 @@
+# 类型化数组与二进制数据
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/typed-arrays.md)
+
+实现位置：`runtime/xt_typed_array.c`、`runtime/xt_array_buffer.c`。
+
+## 类型化数组
+
+- `Uint8Array`、`Int8Array`、`Uint8ClampedArray`、`Uint16Array`、`Int16Array`、`Uint32Array`、`Int32Array`、`Float32Array`、`Float64Array`。
+- 构造：`new X(n)` / `new X(可迭代)` / `new X(buffer[, offset[, length]])` / `X.from` / `X.of`。
+- 属性：`length` / `byteLength` / `byteOffset` / `.buffer` / `BYTES_PER_ELEMENT`。
+- 元素读写按类型强制（`ToIntN` / `ToUintN`、`Uint8ClampedArray` 舍入、`Float32` 单精度舍入）。
+- 原型方法：`fill` / `set` / `slice` / `subarray` / `join` / `toString` / `indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` / `some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` / `at` / `keys` / `values` / `entries`。迭代器方法仍返回数组，而非迭代器对象。
+- 类型化数组是 `ArrayBuffer` 上的视图；`subarray` 共享缓冲区，`slice` 复制。
+
+## ArrayBuffer 与 DataView
+
+- `ArrayBuffer`：`byteLength`、`slice`、`ArrayBuffer.isView`。
+- `DataView`：默认大端，可选 `littleEndian`，支持 Uint8 / Int8 / Uint16 / Int16 / Uint32 / Int32 / Float32 / Float64 的 get/set。
+- 同一缓冲区上的多个视图共享字节。
+
+## 未实现
+
+- `BigInt64Array` / `BigUint64Array`。
+- 基于 `Buffer` 的类型化数组视图。
+- `TextEncoder` / `TextDecoder` 已实现（UTF-8），文档见[字符串与文本](./strings.md)；`structuredClone` 会复制类型化数组。

package/doc/zh-CN/implemented/value-model.md

@@ -0,0 +1,18 @@
+# 值模型与调用约定
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/value-model.md)
+
+实现位置：`src/codegen/values.ts`、`runtime/rt.h`
+
+- 所有 JS 值统一为 64 位 `xt_value`（NaN-boxing）。
+- 双精度浮点不装箱；其它类型为高 16 位 tag + 48 位 payload 的带标签指针。
+- Tag：`undefined` / `null` / `false` / `true` / `string` / `object` / `array` / `function`。
+- 统一函数 ABI：
+
+```c
+xt_value fn(xt_value thisValue, xt_value env, int32_t argc, xt_value *argv);
+```
+
+- `thisValue` 作为首个 ABI 参数线程化（异常安全、支持嵌套）；箭头函数从环境额外槽位词法继承 `this`。
+- 闭包通过 `env` 线程化捕获变量（引用传递，box 包装），直接调用与闭包调用共用同一代码路径。
+- `xt_object` 带原型字段，属性查找沿原型链；`xt_function` 带 `prototype` 与属性包（静态成员）。`xt_array` 也带 `[[Prototype]]`（Array.prototype）。`Object.prototype` 是普通对象的原型根，提供 `hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`；`Object.getPrototypeOf({}) === Object.prototype`。