Implement Vortex subsystem with bytecode instrumentation and telemetry enhancements

.cargo/config.toml

@@ -2,3 +2,5 @@
 # Fast local test cycle without JIT/Python default features.
 test-fast = "test --no-default-features --lib"
 test-backpressure = "test --no-default-features --lib backpressure -- --nocapture"
+# Fast local test cycle for vortex experimental feature.
+test-vortex = "test --no-default-features --features vortex --lib -- --nocapture"

.github/copilot-instructions.md

@@ -19,6 +19,7 @@ Key design decisions & why
 
 Developer workflows (essential commands)
 - Build & test: `cargo test` (CI runs the same). Run entire workspace with `cargo test --manifest-path ./Cargo.toml`.
+- Fast local test alias (defined in `.cargo/config.toml`): `cargo test-fast`, and for Vortex branch: `cargo test-vortex`.
 - Run example: `cargo run --example basic`.
 - Format: `cargo fmt` (project has `rustfmt.toml`).
 - CI: `.github/workflows/ci.yml` runs `cargo test` on push/PR.

.github/workflows/ci.yml

@@ -27,9 +27,9 @@ jobs:
         uses: Swatinem/rust-cache@v2
 
       - name: Build
-        run: cargo build --verbose --features pyo3
+        run: cargo build --verbose --features pyo3,jit,vortex
 
       - name: Run Rust Tests
         env:
           RUST_BACKTRACE: 1
-        run: cargo test --workspace --verbose --features pyo3
+        run: cargo test --workspace --verbose --features pyo3,jit,vortex

Cargo.toml

@@ -13,40 +13,44 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 num_cpus = "*"
-cranelift = { version = "0.87", optional = true }
-cranelift-module = { version = "0.87", optional = true }
-cranelift-jit = { version = "0.87", optional = true }
-cranelift-native = { version = "0.87", optional = true }
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "net", "io-util"] }
 dashmap = "5"
 parking_lot = "0.12"
 bytes = "1"
 tracing = "0.1"
-tracing-subscriber = { version = "0.3", optional = true }
+tracing-subscriber = { version = "0.3", features = ["env-filter", "time"] }
 once_cell = "1"
 crossbeam-channel = "0.5"
 
-# Python (Optional)
-pyo3 = { version = "0.19.2", optional = true }
-pyo3-asyncio = { version = "0.19", features = ["tokio-runtime"], optional = true }
+# Python (Default)
+pyo3 = { version = "0.20", features = ["auto-initialize"], optional = true}
+pyo3-asyncio = { version = "0.20", features = ["tokio-runtime"], optional = true }
+
+# JIT (Optional and experimental)
+cranelift = { version = "0.87", optional = true }
+cranelift-module = { version = "0.87", optional = true }
+cranelift-jit = { version = "0.87", optional = true }
+cranelift-native = { version = "0.87", optional = true }
+wide = { version = "1.2", optional = true }
 
-# Node.js (Optional)
+# Node.js (Optional and currently broken)
 napi = { version = "2.14", default-features = false, features = ["napi4", "tokio_rt", "async"] , optional = true }
 napi-derive = { version = "2.14", optional = true }
 
 [build-dependencies]
 napi-build = { version = "2.0", optional = true }
 
 [features]
-default = ["pyo3", "jit"]
+default = ["pyo3"]
 pyo3 = ["dep:pyo3", "dep:pyo3-asyncio"]
-jit = ["dep:cranelift", "dep:cranelift-module", "dep:cranelift-jit", "dep:cranelift-native"]
+jit = ["dep:cranelift", "dep:cranelift-module", "dep:cranelift-jit", "dep:cranelift-native", "dep:wide"]
 node = ["dep:napi", "dep:napi-derive", "dep:napi-build"]
+vortex = ["pyo3"]
 
 [dev-dependencies]
 futures = "0.3"
 tracing-subscriber = "0.3"
-pyo3 = { version = "0.19.2", features = ["auto-initialize"] }
+pyo3 = { version = "0.20", features = ["auto-initialize"] }
 
 [profile.release]
 opt-level = 3
@@ -56,5 +60,13 @@ panic = "abort"
 strip = true
 
 [profile.dev]
+opt-level = 0
+debug = 0
 strip = true
 panic = "abort"
+incremental = true
+lto = false
+codegen-units = 256
+
+[profile.test]
+panic = "unwind"

README.md

@@ -6,9 +6,9 @@
 ![Language](https://img.shields.io/badge/language-Rust%20%7C%20Python%20%7C%20Node.js-orange.svg?style=for-the-badge&logo=rust)
 ![License](https://img.shields.io/badge/license-AGPL_3.0-green.svg?style=for-the-badge)
 
-**Hybrid distributed runtime fabric for actors, native compute offload, and cross-language services.**
+**Hybrid distributed runtime fabric for actors, cross-language services, and experimental native compute offload.**
 
-[Architecture](docs/architecture.md) • [Usage Guide](docs/usage.md) • [JIT & Offload](docs/jit.md) • [Distributed Mesh](docs/distributed.md)
+[Architecture](docs/architecture.md) • [Usage Guide](docs/usage.md) • [JIT & Offload](docs/jit.md) • [Distributed Mesh](docs/distributed.md) • [Vortex-Transmuter](docs/vortex.md)
 
 </div>
 
@@ -18,7 +18,7 @@
 
 **Iris** is a hybrid distributed runtime built in Rust with first-class **Python** and **Node.js** bindings. It combines three execution styles:
 - **Actor Mesh:** Stateful, message-driven workflows with high concurrency.
-- **Native Offload/JIT:** CPU-heavy hot paths accelerated via Cranelift.
+- **Native Offload/JIT:** CPU-heavy hot paths accelerated via Cranelift. This path is experimental, currently paused, and may be dropped in future releases.
 - **Cross-Language API:** Service-oriented apps mixing Rust, Python, and Node.js.
 
 Iris uses a **cooperative reduction-based scheduler** for fairness, providing built-in supervision, hot swapping, discovery, and location-transparent messaging across nodes.
@@ -34,9 +34,13 @@ Iris uses a **cooperative reduction-based scheduler** for fairness, providing bu
 - **Atomic Hot-Swap:** Update live application logic (Python/Node) without zero downtime.
 - **Global Discovery:** Register and resolve named services locally or over the network.
 - **Self-Healing:** Path-scoped supervisors and structured `EXIT` reasons for fault tolerance.
+- **Vortex-Transmuter (Experimental):** Instruction-bound preemption, transactional ghosting primitives, and guarded bytecode transmutation with explicit fallback telemetry (see [Vortex-Transmuter Guide](docs/vortex.md)).
 - **JIT Acceleration:** Transparently compile Python math functions to native machine code.
     - **Quantum Speculation:** Optional multi-variant JIT selection with runtime telemetry, bounded by compile budget and cooldown controls (see [JIT Internals & Configuration](docs/jit.md)).
 
+    > [!IMPORTANT]
+    > JIT acceleration development is currently paused and may be dropped from the project, while the runtime focuses on actor and cross-language capabilities.
+
 ---
 
 ## Quick Start
@@ -85,13 +89,14 @@ print(fast_math(10.0))
 - [Usage Examples & API Guide](docs/usage.md)
 - [JIT Internals & Configuration](docs/jit.md)
 - [Distributed Mesh & Discovery](docs/distributed.md)
+- [Vortex-Transmuter Guide & Roadmap](docs/vortex.md)
 
 ---
 
 ## Disclaimer
 
 > [!IMPORTANT]
-> **Production Status:** Iris is currently in **Beta**. The JIT/offload APIs are experimental.
+> **Production Status:** Iris is currently in **Beta**. 
 >
 > **Performance (v0.3.0):**
 > - **Push Actors:** 100k+ concurrent actors, ~1.2M+ msgs/sec.

docs/plans/FEAT.md

@@ -86,6 +86,7 @@
 ---
 
 ## ⚫ Safety & Correctness (Functional Runtimes)
+> Delayed for v0.7+
 
 * [ ] **Pure Actor Mode (Optional)**
   Forbid shared mutable state across actors.

docs/usage.md

@@ -214,6 +214,32 @@ rt.set_release_gil_strict(True)
 
 ---
 
+## Vortex controls (Python Runtime, experimental)
+
+When Iris is built with the `vortex` feature, `PyRuntime` exposes automatic ghost-arbitration controls and telemetry.
+
+- `vortex_set_auto_ghost_policy(policy: str) -> bool`
+  - Accepted values: `FirstSafePointWins`, `PreferPrimary`.
+- `vortex_get_auto_ghost_policy() -> Optional[str]`
+- `vortex_get_auto_resolution_counts() -> Tuple[int, int]`
+  - Returns `(primary_wins, ghost_wins)`.
+- `vortex_get_auto_replay_count() -> int`
+- `vortex_reset_auto_telemetry() -> None`
+
+Example:
+
+```python
+rt = Runtime()
+rt.vortex_reset_auto_telemetry()
+rt.vortex_set_auto_ghost_policy("PreferPrimary")
+
+primary_wins, ghost_wins = rt.vortex_get_auto_resolution_counts()
+replayed = rt.vortex_get_auto_replay_count()
+print(primary_wins, ghost_wins, replayed)
+```
+
+---
+
 ## Lifecycle helpers
 
 - `stop(pid: int)` — stop an actor and close mailbox.