bao_engine 0.3.3

SpiderMonkey engine wrapper for Bao runtime
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

// @trace REQ-ENG-001
//! SpiderMonkey engine wrapper. Core types are provided by `bun_sm`;
//! this crate retains only the modules that have complex inter-dependencies
//! (context, job_queue).
//!
//! # Re-export Architecture
//!
//! ```text
//! Layer order (bottom → top):
//!   bun_sm        — 底层：SpiderMonkey 值类型 + JSC API 兼容层 + module_loader
//!                    JSValue, JSGlobalObject, VirtualMachine, CallFrame, JSType, ModuleLoader
//!   bao_engine    — Re-export 层：从 bun_sm re-export 公共类型，保留自有模块
//!                    context, job_queue (复杂内部依赖)
//!   bao_runtime   — 消费层：pub use bao_engine::* (最终替换 bun_jsc::*)
//!   bao_browser   — 消费层：依赖 bao_engine 的 context + dispatch_sm
//! ```
//!
//! ## 迁移步骤 (bun_jsc → bun_sm)
//!
//! 1. **Phase 1 (已完成)**: bao_engine 依赖 bun_sm，re-export 核心类型
//! 2. **Phase 2 (进行中)**: bao_runtime 将 `pub use bun_jsc::*` 改为 `pub use bun_sm::*`
//! 3. **Phase 3 (计划中)**: 移除 bun_jsc 依赖，所有 8,500+ JSC 引用指向 bun_sm
//!
//! ## 约定
//!
//! - **下游 crate 必须通过 `bao_engine::Type` 访问类型，禁止直接 `use bun_sm::Type`**
//!   - 唯一例外：crate 确实需要 bun_sm 中未被 bao_engine re-export 的类型
//!   - 目的：维护单一依赖表面，避免下游 crate 同时依赖 bao_engine 和 bun_sm
//!
//! - 新代码直接使用 `bun_sm::JSValue` 等类型
//! - bao_engine 仅 re-export，不定义值类型
//! - 保留在 bao_engine 的模块（context/job_queue）因内部依赖复杂不迁移
//! - module_loader 已迁移到 bun_sm，通过回调模式（JobQueueDrainFn）避免循环依赖
//!
//! ## 迁移模块到 bun_sm 的步骤
//!
//! 1. 复制 `.rs` 文件到 `bun_sm/src/`
//! 2. 更新 `use crate::` 引用为 bun_sm 自身路径
//! 3. 从 `bao_engine/src/` 删除原文件
//! 4. 在下方 Re-exports 区域添加 `pub use bun_sm::xxx;`
//! 5. 验证：`cargo check -p bao_engine` 通过

// ─── Re-exports from bun_sm (types moved there) ──────────────────────────
// @trace REQ-ENG-001 [entity:BaoRuntime] — SpiderMonkey engine core types (value/error/dispatch) re-exported from bun_sm (mozjs v0.15.14 integration)
// @trace REQ-ENG-007 [api:GET /api/node-compat] — Node.js compat surface (node:fs/path/http/crypto/tls/Buffer/process) bridged via bao_engine re-exports
// @trace REQ-ENG-008 [api:POST /sqlite/open] [entity:SqliteDatabase] — bun:sqlite SpiderMonkey bridge types surfaced through bao_engine
// @trace REQ-ENG-009 [api:POST /ffi/load] [entity:FfiLibrary] — bun:ffi SpiderMonkey bridge types surfaced through bao_engine
// @trace REQ-ENG-010 [entity:FetchTasklet] [api:POST /fetch/async-tasklet] — async fetch/http/https/tls FetchTasklet integration re-export entry
// @trace REQ-ENG-011 [api:/vm/sandbox] [entity:VmSandboxContext] — node:vm sandbox Realm isolation re-export entry
pub use bun_sm::abort_signal;
pub use bun_sm::builtin_name;
pub use bun_sm::codegen;
pub use bun_sm::common_strings;
pub use bun_sm::dispatch_sm;
pub use bun_sm::error;
pub use bun_sm::fetch_headers;
pub use bun_sm::gc;
pub use bun_sm::generated;
pub use bun_sm::host_fn;
pub use bun_sm::ipc;
pub use bun_sm::node_realm_options;
pub use bun_sm::rare_data;
pub use bun_sm::value;
pub use bun_sm::webcore_types;

// ─── Re-exported from bun_sm (migrated from bao_engine) ──────────────────
// @trace REQ-ENG-005 [entity:ModuleSource] [api:POST /module/resolve] — Module Loader bridge (SpiderMonkey ESM hooks → Bun resolver) re-exported from bun_sm
// @trace REQ-ENG-006 [api:GET /api/bun-compat] [entity:BaoRuntime] — Bun.* / Bao.* API adaptation re-export entry (serve/file/fetch/write)
pub use bun_sm::module_loader;
pub use bun_sm::module_loader::{
    GlobalSetupFn, JobQueueDrainFn, PostEvalHook, set_job_queue_drain,
};

// ─── Worker re-exports from bun_sm (REQ-BRW-004) ──────────────────────
// @trace REQ-BRW-004 [entity:Worker] [entity:DedicatedWorkerGlobalScope]
// NOTE: WebWorker bypass removed per DEC-WK-001 BCE-20260627-008.
// Workers route through servo's native Worker::Constructor. The bypass's
// ScopeInitFn / StructuredClone* / install_worker_lifecycle_natives types
// are no longer needed — servo's DedicatedWorkerGlobalScope binding installs
// these natively, and the servo-native scope callback (register_worker_scope_callback)
// is wired directly via worker_scope_init_native in bao_browser/runtime_bridge.rs.

// ─── Modules still owned by bao_engine ───────────────────────────────────
// @trace REQ-ENG-003 [api:POST /host-fn/call] [entity:JsCallback] — host_fn safe FFI wrapper owned module surface (JS call / type conversion / GC root RAII)
// @trace REQ-ENG-004 [api:POST /event-loop/drain] [entity:BaoRuntime] — Event Loop bridge (SpiderMonkey JobQueue → uSockets I/O) owned module surface
// @trace REQ-ENG-001 [entity:BaoRuntime] — engine-native interrupt/timeout/cancellation
// (SpiderMonkey Interrupt.h → ExecutionControl, SM-EVOLUTION #24; internal
// experimental surface, not a stable API commitment)
// @trace REQ-ENG-001 [entity:BaoRuntime] — engine-native memory metering
// (JS::CollectRuntimeStats glue, SM-EVOLUTION #27 裁决 6 → #19 soak;
// internal experimental surface, not a stable API commitment)
pub mod context;
pub mod execution_control;
pub mod job_queue;
// First-writer-wins contract tests for the job-queue embedder hooks.
// Deliberately in the lib #[cfg(test)] target (NOT tests/suite/): the suite
// binary hosts real-router registrations via globals::install_all, and the
// process-global hook registries cannot hold both the synthetic fixture pair
// and the production pair in one process under the fail-closed contract.
#[cfg(test)]
mod job_queue_hook_contract_tests;
pub mod memory_stats;
// @trace REQ-STL-007 [entity:StealthProfile] — engine-native realm identity
// policy sinks: locale (JS_SetDefaultLocale) / Date time precision
// (JS::SetTimeResolutionUsec) / timezone arming for Node-semantics realms
// (SM-EVOLUTION #28, verdict consumed 2026-09-10)
pub mod realm_policy;
// @trace REQ-ENG-001 [entity:JsContext] — engine-native per-JSContext
// stencil cache: compile-once/instantiate-per-realm for repeated global
// script injection (SM-EVOLUTION #26, verdict 2026-09-10; internal
// experimental surface, not a stable API commitment)
pub mod stencil_cache;

// @trace REQ-ENG-012 [entity:BaoStencilXdrCache] — persistent Stencil XDR
// cache: EncodeStencil→disk→DecodeStencil across process restarts, the
// persistence front layer of `stencil_cache` (SM-EVOLUTION #26; internal
// experimental surface, not a stable API commitment)
pub mod xdr_cache;

// @trace REQ-STL-007 [entity:StealthProfile] — Node-semantics realm
// forceUTC arming (creation-time flag consumed by node_realm_options)
pub use bun_sm::global_object::{node_force_utc, set_node_force_utc};

// @trace REQ-ENG-002 [api:POST /codegen/generate] [entity:CodegenBackend] — codegen backend rewrite (.classes.ts → SpiderMonkey bindings) re-exported via bun_sm::codegen / bun_sm::generated

// Re-export proc-macros from bao_engine_macros
pub use bao_engine_macros::codegen_cached_accessors;

// #[macro_export] macros from bun_sm (define_host_fn) are automatically
// available when bao_engine depends on bun_sm — they live at the crate root.
// No explicit `pub use` needed for #[macro_export] macros.

// Higher-tier soft-link providers are dev-deps that nothing in this crate's
// code path `use`s, so cargo never passes them to the linker — GNU ld
// tolerates the undefined faces in test executables, lld-link/COFF does not.
// This test forces them onto the lib-test link line (bao_native_stubs
// force_link precedent in bao_engine's dispatch_sm_tests).
#[cfg(test)]
mod test_link_seams {
    #[test]
    fn link_higher_tier_seams() {
        bao_bundler::force_link_test_seams();
        bun_runtime::webcore_faces::force_link_webcore_faces();
    }
}