Implement Vortex subsystem with bytecode instrumentation and telemetry enhancements by SSL-ACTX · Pull Request #4 · SSL-ACTX/Iris

SSL-ACTX · 2026-04-06T12:26:25Z

This pull request introduces experimental Vortex-Transmuter support, clarifies the project's JIT/offload status, and improves developer workflows and documentation. The most significant changes are the addition of the Vortex execution model (with a comprehensive guide and Python API), updates to dependencies and features in Cargo.toml, and improved test/dev tooling. The JIT/offload path is now marked as experimental and possibly deprecated, while Vortex is documented as the primary experimental path.

Vortex-Transmuter feature and documentation:

Added a detailed docs/vortex.md guide describing the Vortex-Transmuter execution model, its current capabilities, roadmap, API surface, and safety guardrails.
Updated README.md and usage docs to reference the Vortex-Transmuter, its experimental status, and new capabilities (e.g., preemption, ghosting, and transactional primitives). [1] [2] [3] [4] [5]
Added a new Vortex Python API section in docs/usage.md for controlling ghost arbitration and telemetry from Python.

Cargo and dependency updates:

Updated Cargo.toml to:
- Move jit out of default features (now only pyo3 is default).
- Add the vortex feature and related dependencies.
- Upgrade pyo3 and pyo3-asyncio to 0.20, and adjust their default features.
- Add wide as an optional dependency for JIT.
- Enable more tracing-subscriber features.
- Add and document new [profile.dev] settings for faster development builds. [1] [2]

Developer workflow improvements:

Added a new cargo test-vortex alias for fast local testing of the Vortex feature, and documented all test aliases in .github/copilot-instructions.md. [1] [2] [3]

JIT/offload path status and code cleanup:

Updated documentation to clarify that JIT/offload is experimental, currently paused, and may be dropped in future releases. [1] [2] [3]
Cleaned up iris/jit.py by improving import error handling, removing unnecessary type ignores, and adding a logger for JIT meta events. [1] [2] [3] [4] [5]

Project planning and roadmap:

Updated docs/plans/FEAT.md to indicate that "Pure Actor Mode" is delayed for v0.7+.

These changes collectively clarify the project's experimental directions, make Vortex easier to use and test, and improve the reliability and maintainability of both the codebase and developer experience.

…and transactional execution - Added Vortex engine, scheduler, watcher, transmuter, transaction, and rescue pool modules. - Implemented bytecode-level transmutation and reduction checks to manage execution budget. - Integrated Vortex functionality into the Python interface with new functions for budget management and function transmutation. - Enhanced the PyRuntime to utilize Vortex for blocking calls to Python actors. - Added tests for Vortex functionality, including preemption behavior and transaction management.

…error handling

… execution

… handling and code swapping - Introduced new methods in VortexEngine for staging and applying code swaps. - Enhanced transaction management with ghost transactions and resolution policies. - Added support for checkpointing local variables in transactions. - Implemented validation for probe compatibility and rewrite compatibility in vortex bytecode. - Updated tests to cover new transaction features and fallback scenarios. - Improved error reporting for opcode metadata and cache layout issues during function transmutation.

…ced documentation

…to Python runtime

…unction

…cenarios in transmute_function - Part 2 Co-authored-by: Iris Seravelle iris.seravelle@gmail.com

…ntime controls - experimental update 1/? Co-authored-by: Iris Seravelle iris.seravelle@gmail.com

- Introduced `vortex_bytecode` module to handle bytecode operations. - Implemented functionality for verifying and decoding wordcode bytes. - Added support for opcode metadata and quickening. - Created tests for instrumentation, verification of instructions, cache layout, and exception handling. - Enhanced Python integration with new methods for interacting with bytecode. Co-authored-by: Iris Seravelle iris.seravelle@gmail.com

- moved mailbox-related pyo3 tests into `tests/mailbox.rs` - renamed and classified python runtime tests into `tests/timers.rs`, `tests/zero_copy.rs`, and `tests/hot_swap.rs` - merged duplicate registry, network, and supervision pyo3 test files into single category files - removed obsolete split pyo3 test files and cleaned up duplicate test coverage - kept integration-style tests grouped by runtime functionality for clarity and maintainability Co-authored-by: Iris Seravelle iris.seravelle@gmail.com

…mponents

- add robust Python callback wrapper for pyo3 actor execution - wire pid_holder/rt through PoolTask::Execute so pooled Python callbacks can stop the correct actor - stop failed Python actors on callback failure instead of letting exceptions unwind into the runtime - avoid `PyErr::print()` for `SystemExit` to prevent CPython process termination - add regression coverage in `tests/pyo3_runtime.rs` for `SystemExit`, `KeyboardInterrupt`, and `BaseException`

Iris-Seravelle · 2026-04-06T12:32:47Z

tests/test_mbox100k.py

Might need this back?

Iris-Seravelle · 2026-04-06T12:33:06Z

tests/test_100k.py

This one too?

Copilot

Pull request overview

This PR introduces an experimental, feature-gated Vortex subsystem (engine/transmuter/bytecode verifier/transactions/watchdog) and expands developer/test tooling, while also updating Python/JIT/Node integration and logging initialization.

Changes:

Adds the vortex feature with a new runtime subsystem (src/vortex/*) plus extensive Rust integration tests.
Improves PyO3 safety/robustness (panic/exception containment, more integration tests) and initializes tracing via a new src/logging.rs.
Adds Node.js test scripts and updates dependency/features configuration in Cargo.toml plus new cargo aliases.

Reviewed changes

Copilot reviewed 77 out of 86 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/vortex_watcher.rs	Adds basic watcher tests under `vortex` feature.
tests/vortex_transmuter.rs	Adds transmuter budget/instrumentation/execute tests.
tests/vortex_transaction.rs	Adds transaction/ghost resolution tests.
tests/vortex_suite.rs	Adds a test “suite” module stub (currently broken: missing module file).
tests/vortex_scheduler.rs	Adds scheduler stub test.
tests/vortex_rescue_pool.rs	Adds rescue pool counter tests.
tests/vortex_integration_test.rs	Adds runtime-level vortex integration tests.
tests/vortex_engine.rs	Adds extensive engine behavior tests (transactions, swaps, replay).
tests/vortex_bytecode.rs	Adds verifier/instrumentation tests for bytecode utilities.
tests/pyo3_runtime.rs	Consolidates/extends PyO3 runtime tests (exit paths, supervision, zero-copy, etc.).
tests/pyo3_phase7.rs	Fixes PyDict get_item handling for PyO3 0.20 API.
tests/pyo3_registry.rs	Expands registry tests and updates PyO3 API usage.
tests/pyo3_network.rs	Expands network tests and updates PyO3 API usage.
tests/pyo3_mailbox.rs	Expands mailbox tests and updates PyO3 API usage.
tests/pyo3_overflow_policies.rs	Adds bounded mailbox overflow policy tests (one assertion currently too weak).
tests/js/test.js	Adds Node functional tests (push-actor portion mismatches binding message shape).
tests/js/test_nodelatency.js	Adds Node latency benchmark script (currently broken require path).
tests/js/test_node100k.js	Adds Node 100k benchmark script (currently broken require path).
tests/benchmarks/benchmark_pure_py.py	Adds pure-asyncio benchmark script.
tests/benchmarks/benchmark_mbox.py	Adds mailbox benchmark script.
tests/benchmarks/benchmark_jit_t1.py	Adds a JIT benchmark script.
src/vortex/watcher.rs	Adds Vortex watcher (Tokio-spawned loop; currently can panic if no runtime).
src/vortex/vortex_bytecode.rs	Adds guarded bytecode decode/verify/instrument utilities (PyO3).
src/vortex/transmuter.rs	Adds instruction IR + budgeted execution/transmutation stubs.
src/vortex/transaction.rs	Adds transaction + ghost race resolution primitives.
src/vortex/scheduler.rs	Adds scheduler placeholder.
src/vortex/rescue_pool.rs	Adds rescue pool placeholder.
src/vortex/mod.rs	Adds feature-gated Vortex module exports.
src/vortex/engine.rs	Adds Vortex engine (budgeting, swaps, transactions, ghost replay).
src/py/wrappers.rs	Initializes logging and wires in PyO3 Vortex module when enabled.
src/py/utils.rs	Adds `run_python_callback*` helpers (currently won’t compile due to `{:?}` on panic payload).
src/py/pool.rs	Improves Python callback execution handling; stops actor on callback failure.
src/py/mod.rs	Exposes `py::vortex` module behind feature flag.
src/py/jit/mod.rs	Refactors imports/formatting; keeps unwind safety.
src/py/jit/config.rs	Ensures logging is initialized before emitting tracing logs.
src/py/jit/codegen/registry.rs	Formatting changes.
src/py/jit/codegen/quantum.rs	Formatting changes.
src/py/jit/codegen/mod.rs	Reorders modules/exports; adds a test for vector unary eval pair.
src/py/jit/codegen/lowering.rs	Formatting change.
src/py/jit/codegen/jit_module.rs	Formatting change.
src/py/jit/codegen/exec.rs	Refactors argument extraction (uses safe PyO3 APIs) + formatting.
src/py/jit/codegen/eval.rs	Switches SIMD pair-eval to `wide::f64x2`.
src/py/jit/codegen/compiler.rs	Formatting changes.
src/py/jit/codegen/buffer.rs	Minor import/formatting cleanup.
src/node.rs	Minor change in `Backpressure` formatting, but `message_to_js` currently has tuple-shape compile issues.
src/mailbox.rs	Formatting tweaks in tests.
src/logging.rs	Adds global tracing subscriber initialization helper.
README.md	Updates docs to position Vortex as the primary experimental path; marks JIT as paused/possibly deprecated.
iris/jit.py	Improves optional import handling + adds structured logger for meta events.
docs/vortex.md	Adds comprehensive Vortex guide/roadmap/guardrail documentation.
docs/usage.md	Adds Python Vortex controls section.
docs/plans/FEAT.md	Marks “Pure Actor Mode” as delayed to v0.7+.
Cargo.toml	Adds `vortex` feature, adjusts defaults, adds `wide`, enables tracing-subscriber features, and changes dev profile settings.
.github/copilot-instructions.md	Documents new test aliases.
.cargo/config.toml	Adds `cargo test-vortex` alias.

Copilot · 2026-04-06T12:33:09Z

src/py/utils.rs

+    match result {
+        Ok(Ok(())) => true,
+        Ok(Err(())) => false,
+        Err(payload) => {
+            eprintln!("[Iris] Python actor unwind: {:?}", payload);
+            false
+        }


catch_unwind returns a Box<dyn Any + Send>, which does not implement Debug. The eprintln!("... {:?}", payload) line will not compile. Convert the panic payload to a string (e.g., downcast to &str/String) or log a fixed message without formatting the payload.

Copilot · 2026-04-06T12:33:09Z

src/vortex/watcher.rs

+    pub fn enable(&self) {
+        if self
+            .enabled
+            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+            .is_ok()
+        {
+            let enabled = self.enabled.clone();
+            tokio::spawn(async move {
+                while enabled.load(Ordering::Relaxed) {
+                    // In a full implementation, this would inspect actor liveness + preemption counters,
+                    // and potentially escalate via OS-level signal (SIGVTALRM) or internal throttling.
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                }
+            });


VortexWatcher::enable() calls tokio::spawn(...) unconditionally. If this is invoked from a thread without an active Tokio runtime (e.g., from a synchronous API surface), it will panic. Consider using tokio::runtime::Handle::try_current() and spawning via that handle (or returning an error/false when no runtime is available).

tests/pyo3_runtime.rs

Copilot · 2026-04-06T12:33:10Z

tests/pyo3_runtime.rs

+            // Check that the reason string indicates a panic
+            let reason: String = msg.getattr(py, "reason").unwrap().extract(py).unwrap();
+            assert_eq!(
+                reason, "normal",
+                "Exit reason to supervisor should be 'panic'"
+            );


The assertion message contradicts the actual expectation: it checks reason == "normal" but the failure text says it should be 'panic'. Update the message (or the expected value) so the test is self-consistent and communicates the intended behavior.

tests/vortex_suite.rs

Cargo.toml

Copilot · 2026-04-06T12:33:11Z

src/node.rs

            let (type_name, target_pid) = match sys {
                SystemMessage::Exit(info) => (
                    "EXIT",
                    Some(info.from as i64),
                    match info.reason {
                        crate::mailbox::ExitReason::Normal => Some("normal".to_string()),
                        crate::mailbox::ExitReason::Panic => Some("panic".to_string()),
                        crate::mailbox::ExitReason::Timeout => Some("timeout".to_string()),
                        crate::mailbox::ExitReason::Killed => Some("killed".to_string()),
                        crate::mailbox::ExitReason::Oom => Some("oom".to_string()),
                        crate::mailbox::ExitReason::Other(ref s) => Some(s.clone()),
                    },
                    info.metadata.clone(),
                ),
                SystemMessage::HotSwap(_) => ("HOT_SWAP", None),
                SystemMessage::Ping => ("PING", None, None, None),
                SystemMessage::Pong => ("PONG", None, None, None),
-                SystemMessage::Backpressure(level) => (
-                    "BACKPRESSURE",
-                    None,
-                    Some(level.as_str().to_string()),
-                    None,
-                ),
+                SystemMessage::Backpressure(level) => {
+                    ("BACKPRESSURE", None, Some(level.as_str().to_string()), None)
+                }


In message_to_js, the tuple destructuring and match arms don’t line up: let (type_name, target_pid) = match sys { ... } but some arms return 4-tuples and the code later uses reason / metadata. As written, this won’t compile when the node feature is enabled. Align the destructuring with the returned tuple shape (e.g., bind type_name, target_pid, reason, metadata consistently in all arms).

Iris-Seravelle

Looking good, just needs some cleaning.

Cargo.toml

- move Vortex inline tests out of source modules into tests/vortex - update README to note JIT acceleration is paused and may be dropped - adjust Cargo feature wiring for vortex/pyo3 and JIT dependencies Co-authored-by: Iris Seravelle iris.seravelle@gmail.com

… dispatch - initialize vortex genetic history entries for budgeted and virtual actor spawn paths - remove vortex genetic history entries during actor exit cleanup - make genetic history progress deterministic across suspend/cycle execution paths - increment genetic totals on successful enqueue so history reflects delivered traffic - optimize send_user hot path by mutating counters in place (get_mut) instead of remove+insert - align VIO replay accounting to count attempted calls before stopping on executor failure - prevent actor-strategy offload calls from accidentally hitting stale JIT entries - add per-function offload strategy tracking to isolate actor vs JIT dispatch behavior - fix CI-only pyo3_jit async decorator flake caused by cross-test JIT state leakage - keep vortex_engine, pyo3_vortex, and pyo3_jit suites passing under vortex+jit+pyo3 feature runs

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Iris Seravelle <iris.seravelle@gmail.com>

SSL-ACTX added 15 commits March 20, 2026 05:04

feat(vortex): enhance bytecode instrumentation with verification and …

ffd600a

…error handling

feat(vortex): implement guard telemetry and verification for bytecode…

a94d250

… execution

docs(vortex): update README and add Vortex-Transmuter guide for enhan…

658a2f5

…ced documentation

feat(vortex): add automatic ghost arbitration controls and telemetry …

1912c19

…to Python runtime

feat(vortex): enhance exception handling and telemetry in transmute_f…

9f182ed

…unction

feat(vortex): enhance exception handling and telemetry for fallback s…

3b1fc55

…cenarios in transmute_function - Part 2 Co-authored-by: Iris Seravelle iris.seravelle@gmail.com

feat(vortex): implement genetic budgeting primitive and associated ru…

eb54d3f

…ntime controls - experimental update 1/? Co-authored-by: Iris Seravelle iris.seravelle@gmail.com

fix(jit): fixed a regression where logging of jit isn't working

097f0f6

feat(logging): add logging module and initialize logger in various co…

b2899d0

…mponents

fix(vortex): handle missing items in locals with proper error handling

354e48f

SSL-ACTX requested a review from Iris-Seravelle April 6, 2026 12:26

SSL-ACTX self-assigned this Apr 6, 2026

Copilot AI review requested due to automatic review settings April 6, 2026 12:26

SSL-ACTX added documentation Improvements or additions to documentation enhancement New feature or request labels Apr 6, 2026

Copilot started reviewing on behalf of SSL-ACTX April 6, 2026 12:27 View session

Iris-Seravelle reviewed Apr 6, 2026

View reviewed changes

tests/test_mbox100k.py Outdated

Copy link
Copy Markdown

Collaborator

Iris-Seravelle Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might need this back?

Iris-Seravelle reviewed Apr 6, 2026

View reviewed changes

tests/test_100k.py Outdated

Copy link
Copy Markdown

Collaborator

Iris-Seravelle Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one too?

Copilot AI reviewed Apr 6, 2026

View reviewed changes

Iris-Seravelle requested changes Apr 6, 2026

View reviewed changes

Cargo.toml Show resolved Hide resolved

SSL-ACTX force-pushed the vortex branch from 02fdbdf to 20044f2 Compare April 6, 2026 12:55

SSL-ACTX added 2 commits April 6, 2026 21:01

chore(vortex): remove unused vortex test suite

60c57cb

SSL-ACTX force-pushed the vortex branch from 384c991 to 495cf30 Compare April 6, 2026 14:18

chore: update Cargo.toml

4c6c1ed

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Iris Seravelle <iris.seravelle@gmail.com>

Iris-Seravelle merged commit 14bd68e into main Apr 6, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement Vortex subsystem with bytecode instrumentation and telemetry enhancements#4

Implement Vortex subsystem with bytecode instrumentation and telemetry enhancements#4
Iris-Seravelle merged 19 commits intomainfrom
vortex

SSL-ACTX commented Apr 6, 2026

Uh oh!

Iris-Seravelle Apr 6, 2026

Uh oh!

Iris-Seravelle Apr 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Iris-Seravelle left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

SSL-ACTX commented Apr 6, 2026

Uh oh!

Iris-Seravelle Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Iris-Seravelle Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Iris-Seravelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants