OxideJS：面向 AI Agent 的轻量级 JavaScript 执行引擎

1. 项目简介

OxideJS 是一个基于 Rust 的轻量级 JavaScript 执行引擎，擅长短时、高频、即时执行的脚本运行场景，主要面向 Agent 工具调用、脚本沙箱、数据转换流水线和嵌入式运行时。

当前项目聚焦于实用 ECMAScript 子集，并通过 test262 持续验证兼容性。我们的最终目标是提供一个小型、可检查、跨平台、启动成本可预测、benchmark 可复现的 JavaScript runtime。

2. 特性概览

• Rust 实现：使用 Cargo workspace 组织 parser、compiler、VM、runtime、CLI 和 test runner。
• 自研引擎：自研字节码、寄存器式虚拟机、对象模型和运行时状态管理。
• 寄存器式 VM：使用固定寄存器文件执行字节码，减少栈式 VM 中频繁 push/pop 的开销。
• NaN-boxing 值表示：用 64-bit 值统一表示 number、boolean、object、string、null 和 undefined。
• Shape 对象布局：使用隐藏类思想描述对象属性布局，便于缓存属性偏移。
• Inline Cache 方向：围绕 shape/offset 缓存设计属性访问路径。
• 共享运行时 Kernel：KernelCore 永久共享 key 驻留 / Shape / 编译缓存 / IC 模板, KernelSession 按会话管理 BuiltinWorld 与 global object。
• test262 runner：内置兼容性测试运行器，输出 pass / fail / skip 统计。

3. 架构

OxideJS 采用经典的 parse -> compile -> execute 流水线，同时使用 单 Kernel、多 VM 的运行时结构。Kernel 内部分为两层：KernelCore 永久共享 (PermInterner / Shape / Code / Prop)，KernelSession 按会话可重建 (BuiltinWorld / global object)；多个 oxide_vm 实例面向不同执行请求独立运行。

                         +-----------------------+
                         |     oxide_kernel      |
                         |-----------------------|
                         | KernelCore            |
                         |  PermInterner         |  append-only key 驻留
                         |  ShapeForge           |  Shape / Hidden Class 表
                         |  CodeForge            |  bytecode LRU 缓存
                         |  PropForge            |  IC 模板
                         |-----------------------|
                         | KernelSession         |  可 full_reset() 重建
                         |  BuiltinWorld         |
                         |  Global object        |
                         |  BuiltinSnapshot      |
                         +----------+------------+
                                    |
          shared Arc<KernelCore>  |  + per-VM KernelSession
                 +-----------------+-----------------+
                 |                 |                 |
                 v                 v                 v
        +----------------+ +----------------+ +----------------+
        |    oxide_vm    | |    oxide_vm    | |    oxide_vm    |
        |----------------| |----------------| |----------------|
        |  registers     | |  registers     | |  registers     |
        |  call frames   | |  call frames   | |  call frames   |
        |  Epoch Arena   | |  Epoch Arena   | |  Epoch Arena   |
        |  JsString GC   | |  JsString GC   | |  JsString GC   |
        +-------+--------+ +-------+--------+ +-------+--------+
                |                  |                  |
                v                  v                  v
        JsValue Result     JsValue Result     JsValue Result

Per request pipeline:

 JavaScript Source
        |
        v
+------------------+
|   oxide_parser   |  解析源码，生成 AST
+------------------+
        |
        v
+------------------+
| oxide_compiler   |  AST 编译为寄存器式字节码；可命中 KernelCore.CodeForge
+------------------+
        |
        v
+------------------+
|    oxide_vm      |  从 VM Pool 获取实例并执行字节码
+------------------+

核心组件：

1. Parser 前端：通过 oxide_parser 将源码解析为 AST。
2. 字节码编译器：将 AST 降低为 OxideJS 字节码、常量池和寄存器布局。
3. 寄存器式 VM：oxide_vm 读取字节码并使用固定寄存器文件执行；每个 VM 持有自己的寄存器、调用栈、Epoch Arena 与 JsString GC。
4. 值系统：JsValue 通过 NaN-boxing 紧凑表示 JavaScript 运行时值；JsString 由 VM 内的标记清扫 GC 管理。
5. 对象模型：对象通过 Shape ID 描述属性布局。
6. 运行时 Kernel：KernelCore 保存进程级永久共享状态 (PermInterner 等), KernelSession 保存可重建的会话级状态 (BuiltinWorld / global object); 多个 VM 通过 Arc<KernelCore> 引用同一份永久共享数据。
7. 内置对象层：常用内置对象和方法由 Rust 原生实现，通过 BuiltinWorld 注册。
8. 兼容性测试层：oxide_test262 运行 test262 用例并输出统计结果，支持 --supervise 子进程窗口模式实现单测超时与断点续跑。

4. 仓库结构

project-root/
├── Cargo.toml
├── README.md
├── crates/
│   ├── oxide_parser/      # JavaScript parser 接入层
│   ├── oxide_compiler/    # AST -> bytecode 编译器
│   ├── oxide_types/       # JsValue、JsObject、Shape、内存基础类型
│   ├── oxide_kernel/      # 共享运行时状态和内置对象注册
│   ├── oxide_vm/          # 字节码 VM 和运行时执行逻辑
│   ├── oxide_api/         # 嵌入式 API 预留层
│   ├── oxide_cli/         # 命令行工具
│   └── oxide_test262/     # test262 兼容性测试运行器
└── tests/
    └── test262/           # 本地 test262 测试套件

5. 构建

构建全部 crate

cargo build --release

运行单元测试

cargo test

6. CLI 使用

执行源码片段

cargo run --release -p oxide_cli -- eval "1 + 2"

执行文件

cargo run --release -p oxide_cli -- run examples/demo.js

打印编译后的字节码

cargo run --release -p oxide_cli -- compile -e "1 + 2"

启动 REPL

cargo run --release -p oxide_cli

7. test262 兼容性测试

OxideJS 包含独立的 test262 runner：

cargo run --release -p oxide_test262

运行指定子目录：

cargo run --release -p oxide_test262 -- tests/test262/test language/expressions

runner 会输出：

• 发现的测试文件总数；
• pass / fail / skip 数量；
• 全量通过率；
• 实际执行样本通过率；
• 失败类别统计；
• 按目录拆分的结果（取决于 runner 版本）。

兼容性数字属于开发过程指标。发布正式 benchmark 或兼容性结论前，应基于当前 checkout 的 test262 版本重新生成结果。

8. Benchmark

Benchmark 工作围绕可复现脚本和可比较 baseline 展开。

计划中的 benchmark 分组：

分组	目的	状态
表达式 microbenchmark	算术、比较、逻辑操作	planned
对象 / 属性访问 benchmark	对象创建和属性访问路径	planned
Array / String benchmark	常用内置对象操作	planned
函数调用 benchmark	字节码 call/return 与 native call 开销	planned
Agent 风格 workload	短时、重复结构脚本和数据转换	planned
JetStream 2.0 子集	依赖兼容性的 JS benchmark 覆盖	planned

当前研究用 baseline：

• QuickJS
• Boa
• JerryScript

[TODO] 完工时放与其他 baseline 的对比表格

9. 主要使用的开源项目

• oxc — JavaScript 源码解析，因为这不是我们的工作中心，所以没有自己构建该系统
• bumpalo — Bump allocator，构成 Epoch arena 内存系统的底层分配器
• dashmap — 并发 HashMap，用于 CodeForge、ShapeForge、PropForge 跨 VM 缓存共享

10. License

本项目采用 MIT License 开源协议。详见 LICENSE。