fix(python-guest): persist module globals across run() calls (#93)

* fix(python-guest): persist module globals across run() calls

The Executor previously rebuilt the globals dict on every call to run() via an inline 'exec(code, {...})' literal. That silently discarded every 'def', 'class', and top-level assignment between runs on the same sandbox instance, breaking three documented contracts:

  * WasmSandbox's snapshot/restore is the mechanism for rewinding guest state - a bare back-to-back run() boundary was never specified as a state-wipe.

  * The python_basics example explicitly sets 'counter = 100' and only expects it to disappear after restore(); the prior implementation made restore() a no-op because the counter would have been wiped by the very next run() anyway.

  * The JS guest preserves globalThis across run() calls; the Python guest had no equivalent persistence path.

Fix: construct the globals dict once in Executor.__init__ and pass the instance attribute to every exec(). Snapshot/restore continues to rewind the namespace because it lives in the guest's Wasm linear memory.

Adds tests/python_state_persistence.rs covering: top-level def reuse, bare assignment reuse, and snapshot/restore rewind of the persistent namespace.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

* Allow uv prerelease resolution

Signed-off-by: James Sturtevant <jsturtevant@gmail.com>

* Clean up Python state persistence tests

Signed-off-by: James Sturtevant <jsturtevant@gmail.com>

---------

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>
Signed-off-by: James Sturtevant <jsturtevant@gmail.com>
Co-authored-by: James Sturtevant <jsturtevant@gmail.com>

Author: simongdavies

pyproject.toml

@@ -5,6 +5,7 @@ requires-python = ">=3.10"
 
 [tool.uv]
 package = false
+prerelease = "allow"
 
 [tool.uv.workspace]
 members = [

src/wasm_sandbox/guests/python/sandbox_executor.py

@@ -139,7 +139,36 @@ def _http_request(method: str, url: str, body: str = "", content_type: str = "")
 
 
 class Executor:
-    """Implements the WIT executor interface for componentize-py."""
+    """Implements the WIT executor interface for componentize-py.
+
+    The executor keeps a single, persistent module-level namespace
+    (``self._globals``) that is reused across every call to :py:meth:`run`.
+    Names defined by guest code (``x = 1``, ``def foo(): ...``,
+    ``class C: ...``) therefore remain visible to subsequent runs on
+    the same sandbox instance, matching:
+
+      * the snapshot/restore contract documented on ``WasmSandbox`` —
+        ``snapshot``/``restore`` is the mechanism for rewinding state,
+        not bare back-to-back ``run`` calls;
+      * the JavaScript guest's ``globalThis`` persistence story for
+        explicit global writes;
+      * the ``python_basics`` example, which sets ``counter = 100``
+        and treats ``restore`` (not the next ``run``) as the action
+        that makes ``counter`` undefined.
+
+    Host-provided helpers (``call_tool``, ``http_get``, ``http_post``)
+    are seeded once on construction. Guest code may shadow them
+    locally, but the originals are restored by ``snapshot``/``restore``
+    along with the rest of the namespace.
+    """
+
+    def __init__(self) -> None:
+        self._globals: dict = {
+            "__builtins__": __builtins__,
+            "call_tool": _call_tool,
+            "http_get": http_get,
+            "http_post": http_post,
+        }
 
     def run(self, code: str) -> ExecutionResult:
         """Execute Python code and capture output."""
@@ -152,7 +181,7 @@ def run(self, code: str) -> ExecutionResult:
 
         exit_code = 0
         try:
-            exec(code, {"__builtins__": __builtins__, "call_tool": _call_tool, "http_get": http_get, "http_post": http_post})
+            exec(code, self._globals)
         except SystemExit as e:
             exit_code = e.code if isinstance(e.code, int) else 1
         except Exception as e:

src/wasm_sandbox/tests/python_state_persistence.rs

@@ -0,0 +1,133 @@
+//! Integration test: Python guest module globals persist across `run()`.
+//!
+//! This test pins the documented contract that the Python `Executor`
+//! reuses one module-level namespace for every call to `run()` on the
+//! same sandbox instance. It tests:
+//!
+//!   * the `WasmSandbox` `snapshot`/`restore` resets state — the documented
+//!     mechanism for rewinding guest state
+//!   * if state otherwise survives a `run()` boundary
+//!   * behaves like the JavaScript guest, which preserves `globalThis` across runs
+//!
+
+use std::path::Path;
+
+use hyperlight_sandbox::SandboxBuilder;
+use hyperlight_wasm_sandbox::Wasm;
+
+fn python_guest_path() -> String {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("guests/python/python-sandbox.aot")
+        .display()
+        .to_string()
+}
+
+/// A `def` at module top level in `run()` must be callable in the second `run()`
+#[test]
+fn python_function_definition_persists_across_runs() {
+    let mut sandbox = SandboxBuilder::new()
+        .guest(Wasm)
+        .module_path(python_guest_path())
+        .build()
+        .expect("failed to create sandbox");
+
+    let snap = sandbox.snapshot().expect("snapshot failed");
+    sandbox
+        .run("def word_count(text): return len(text.split())")
+        .expect("first run failed");
+
+    let persist_result = sandbox
+        .run("print(word_count('hello world from hyperlight'))")
+        .expect("second run failed");
+
+    sandbox.restore(&snap).expect("restore failed");
+    let reset_result = sandbox
+        .run(
+            r#"
+try:
+    print(word_count('hello world from hyperlight'))
+except NameError:
+    print("word_count is undefined")
+"#,
+        )
+        .expect("post-restore run failed");
+
+    assert_eq!(
+        persist_result.exit_code, 0,
+        "stderr: {}",
+        persist_result.stderr
+    );
+    assert_eq!(persist_result.stdout.trim(), "4");
+    assert_eq!(reset_result.exit_code, 0, "stderr: {}", reset_result.stderr);
+    assert_eq!(reset_result.stdout.trim(), "word_count is undefined");
+}
+
+/// A bare module-level assignment in `run()` must be readable in the second `run()`
+#[test]
+fn python_top_level_assignment_persists_across_runs() {
+    let mut sandbox = SandboxBuilder::new()
+        .guest(Wasm)
+        .module_path(python_guest_path())
+        .build()
+        .expect("failed to create sandbox");
+
+    let snap = sandbox.snapshot().expect("snapshot failed");
+    sandbox.run("counter = 100").expect("first run failed");
+    let persist_result = sandbox
+        .run("print(f'counter = {counter}')")
+        .expect("second run failed");
+
+    sandbox.restore(&snap).expect("restore failed");
+    let reset_result = sandbox
+        .run(
+            r#"
+try:
+    print(f'counter = {counter}')
+except NameError:
+    print("counter is undefined")
+"#,
+        )
+        .expect("post-restore run failed");
+
+    assert_eq!(
+        persist_result.exit_code, 0,
+        "stderr: {}",
+        persist_result.stderr
+    );
+    assert_eq!(persist_result.stdout.trim(), "counter = 100");
+    assert_eq!(reset_result.exit_code, 0, "stderr: {}", reset_result.stderr);
+    assert_eq!(reset_result.stdout.trim(), "counter is undefined");
+}
+
+/// `snapshot` + `restore` must continue to rewind the persistent
+/// namespace, undoing any names defined since the snapshot. This is
+/// the contract documented on `WasmSandbox`; the persistence fix must
+/// not regress it.
+#[test]
+fn python_restore_rewinds_module_globals() {
+    let mut sandbox = SandboxBuilder::new()
+        .guest(Wasm)
+        .module_path(python_guest_path())
+        .build()
+        .expect("failed to create sandbox");
+
+    let snap = sandbox.snapshot().expect("snapshot failed");
+    sandbox
+        .run("rolled_back = 'still here'")
+        .expect("set failed");
+    sandbox.restore(&snap).expect("restore failed");
+
+    let result = sandbox
+        .run(
+            r#"
+try:
+    print(rolled_back)
+except NameError:
+    print("rolled_back is undefined")
+"#,
+        )
+        .expect("post-restore run failed");
+
+    assert_eq!(result.exit_code, 0, "stderr: {}", result.stderr);
+    assert_eq!(result.stdout.trim(), "rolled_back is undefined");
+}