docs(vm): discuss execution architecture redesign

.gitignore

@@ -3,3 +3,4 @@
 *.profraw
 *.profdata
 __pycache__/
+/docs/reports/primitive-vm-s09-fair-three-rounds.json

Cargo.toml

@@ -18,6 +18,8 @@ default = []
 test262-host = []
 test-support = []
 profiling = []
+# Temporary migration configuration; default switching and bridge removal belong to S10.
+stack-vm = []
 [dev-dependencies]
 quickjs-oxide-host = { workspace = true, features = ["engine-test-support"] }
 

README.md

@@ -58,12 +58,12 @@ Neither is a general untrusted-bytecode loader or Feature Parity claim.
 
 ## Status
 
+- [Documentation index](docs/README.md)
 - [Engine module responsibilities](docs/architecture.md)
 - [Current implementation status](docs/status.md)
+- [Stack VM redesign: goals and architecture](docs/primitive-vm-plan.md)
+- [Stack VM redesign: 10-commit implementation plan](docs/primitive-vm-commit-plan.md)
 - [Profiling and external benchmarks](docs/profiling.md)
-- [Data structure improvement plan](docs/data-structure-plan.md)
-- [Published bytecode and VM execution plan](docs/published-execution-plan.md)
-- [Published execution contracts](docs/published-execution-contracts.md)
 - [Pinned Test262 baseline and metric definitions](docs/test262.md)
 - [Parity acceptance contract](docs/parity.md)
 - [Playground build and trust boundary](docs/playground.md)
@@ -90,12 +90,11 @@ npm ci && npx playwright install chromium && npm run test:browser
 The root quickjs-oxide package has three source modules: `source/` for authored
 text and Unicode support, `regexp/` for regex programs and matching, and
 `engine/` for the interpreter's responsibility modules. `src/lib.rs` is the
-only top-level Rust source file. Each source directory documents its ownership
-in a README.
+only top-level Rust source file.
 
 Native and browser providers live in `adapters/`, applications in `apps/`,
 and the Test262 runner in `conformance/test262`. See
-[architecture](docs/architecture.md) and [source guide](src/README.md).
+[architecture](docs/architecture.md) for responsibilities and boundaries.
 
 ```sh
 cargo run -p quickjs-oxide-cli -- -e 'print(6 * 7)'

adapters/native/Cargo.toml

@@ -14,4 +14,5 @@ quickjs-oxide = { workspace = true }
 tz-rs = { workspace = true }
 
 [features]
+stack-vm = ["quickjs-oxide/stack-vm"]
 engine-test-support = []

adapters/web/Cargo.toml

@@ -13,3 +13,6 @@ workspace = true
 quickjs-oxide = { workspace = true }
 js-sys = { workspace = true }
 wasm-bindgen = { workspace = true }
+
+[features]
+stack-vm = ["quickjs-oxide/stack-vm"]

apps/cli/Cargo.toml

@@ -21,6 +21,7 @@ path = "src/main.rs"
 default = []
 test262-host = ["quickjs-oxide/test262-host"]
 profiling = ["quickjs-oxide/profiling"]
+stack-vm = ["quickjs-oxide/stack-vm"]
 
 [dev-dependencies]
 quickjs-oxide = { workspace = true, features = ["test-support"] }

apps/cli/examples/compile_probe.rs

@@ -0,0 +1,46 @@
+//! Public compile API timing: source I/O, Runtime/Context creation, execution,
+//! and teardown are outside the measured interval.
+use quickjs_oxide::engine::api::Runtime;
+use quickjs_oxide_host::SystemHostServices;
+use std::{env, fs, time::Instant};
+
+fn main() {
+    let path = env::args().nth(1).expect("source path");
+    if path == "--version" {
+        println!("oxide-compile-probe 1");
+        return;
+    }
+    let source = fs::read_to_string(&path).expect("UTF-8 benchmark source");
+    #[cfg(feature = "profiling")]
+    let costs = quickjs_oxide::engine::api::profiling::CostProfile::start();
+    let runtime = Runtime::new_with_host_services(SystemHostServices::default());
+    let mut context = runtime.new_context();
+    let started = Instant::now();
+    let function = context
+        .compile_with_filename(&source, &path)
+        .expect("compile frozen script");
+    let elapsed = started.elapsed().as_nanos();
+    std::hint::black_box(&function);
+    println!("compile_ns:{elapsed}");
+    // An instrumented probe is deliberately inadmissible as formal timing:
+    // replay.py requires empty stderr. Use this only for phase attribution.
+    #[cfg(feature = "profiling")]
+    {
+        let snapshot = costs.snapshot();
+        for (name, phase) in [
+            ("parse", snapshot.parse),
+            ("resolution", snapshot.resolution),
+            ("lowering", snapshot.lowering),
+            ("blocks", snapshot.blocks),
+            ("fusion", snapshot.fusion),
+            ("relocation", snapshot.relocation),
+            ("verify", snapshot.verify),
+            ("publish", snapshot.publish),
+        ] {
+            eprintln!(
+                "{{\"phase\":\"{name}\",\"attempts\":{},\"inclusive_ns\":{},\"exclusive_ns\":{}}}",
+                phase.attempts, phase.inclusive_ns, phase.exclusive_ns
+            );
+        }
+    }
+}