test(runtime): assert guest-observed wasi:clocks time under a ManualClock override

Add a clock-reader fixture that reads the WASI wall clock through std on
every event and logs it, plus a harness test that pins a ManualClock,
boots the fixture under that override, dispatches a block, and asserts the
guest logged the pinned instant rather than the ambient host clock. This
proves the WasiClockOverride reaches the guest end to end, not just the
host boot path.

Author: mfw78

.github/workflows/ci.yml

@@ -57,7 +57,7 @@ jobs:
           cargo build --release --target wasm32-wasip2 --locked
           -p example -p twap-monitor -p ethflow-watcher -p price-alert
           -p balance-tracker -p stop-loss -p http-probe -p echo-venue
-          -p echo-client -p flaky-bomb -p fuel-bomb -p memory-bomb -p panic-bomb
+          -p echo-client -p clock-reader -p flaky-bomb -p fuel-bomb -p memory-bomb -p panic-bomb
       - run: cargo test --workspace --all-features --no-fail-fast --locked
 
   docs:

Cargo.lock

@@ -20,6 +20,7 @@ members = [
     "modules/examples/http-probe",
     "modules/examples/price-alert",
     "modules/examples/stop-loss",
+    "modules/fixtures/clock-reader",
     "modules/fixtures/flaky-bomb",
     "modules/fixtures/fuel-bomb",
     "modules/fixtures/memory-bomb",

Cargo.toml

@@ -609,4 +609,61 @@ direction = "above"
         rt.shutdown();
         rt.wait().await.expect("clean shutdown");
     }
+
+    /// The guest observes the `WasiClockOverride` end to end: pin the harness
+    /// clock to a known instant, boot the clock-reader fixture under it, and
+    /// dispatch a block. The fixture reads `wasi:clocks/wall-clock` through
+    /// `std` and logs the wall time as whole seconds, so the logged value
+    /// equalling the pinned instant (and not the ambient host clock) proves
+    /// the override reaches the guest, not just the host boot path.
+    #[tokio::test]
+    async fn harness_guest_observes_the_clock_override() {
+        use std::time::{Duration, UNIX_EPOCH};
+
+        let Some(wasm) = module_wasm_or_skip("clock_reader.wasm") else {
+            return;
+        };
+
+        // A round instant far from the ambient clock: a stale ambient read
+        // would land in the 1.7-billion-plus range of the present, so an
+        // exact match on this value can only come from the override.
+        const PINNED_SECS: u64 = 1_700_000_000;
+
+        let builder = TestRuntime::builder(wasm).manifest_inline(block_manifest("clock-reader", 1));
+        builder
+            .clock()
+            .set(UNIX_EPOCH + Duration::from_secs(PINNED_SECS));
+
+        let mut rt = builder
+            .launch()
+            .await
+            .expect("launch clock-reader over the harness");
+
+        rt.push_block(header_numbered(19_000_000));
+        let record = rt
+            .wait_for_log("clock-reader", &format!("clock wall {PINNED_SECS}"))
+            .await
+            .expect("the guest logs its wall-clock reading after dispatch");
+
+        // The line is a host-interface log carrying exactly the pinned
+        // seconds, parsed back to guard against a substring false positive.
+        assert_eq!(
+            record.source,
+            crate::host::logs::LogSource::HostInterface,
+            "the fixture logs through the host interface",
+        );
+        let logged: u64 = record
+            .message
+            .rsplit(' ')
+            .next()
+            .and_then(|s| s.parse().ok())
+            .expect("the log line ends in the wall-clock seconds");
+        assert_eq!(
+            logged, PINNED_SECS,
+            "the guest read the overridden wall clock, not the ambient host clock",
+        );
+
+        rt.shutdown();
+        rt.wait().await.expect("clean shutdown");
+    }
 }

crates/nexum-runtime/src/test_utils/harness.rs

@@ -98,5 +98,5 @@ ci:
     cargo build --release --target wasm32-wasip2 \
         -p example -p twap-monitor -p ethflow-watcher -p price-alert \
         -p balance-tracker -p stop-loss -p http-probe -p echo-venue \
-        -p echo-client -p flaky-bomb -p fuel-bomb -p memory-bomb -p panic-bomb
+        -p echo-client -p clock-reader -p flaky-bomb -p fuel-bomb -p memory-bomb -p panic-bomb
     cargo test --workspace --all-features --no-fail-fast

justfile

@@ -0,0 +1,13 @@
+[package]
+name = "clock-reader"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Test fixture: on every event reads the WASI wall clock through std and logs it. Lets a test assert the guest observes a WasiClockOverride end to end."
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wit-bindgen = { version = "0.58", default-features = false, features = ["macros", "realloc"] }

modules/fixtures/clock-reader/Cargo.toml

@@ -0,0 +1,21 @@
+# clock-reader test fixture. Subscribes to a single chain's blocks so the
+# supervisor invokes `on_event` once per block; the handler reads the WASI
+# wall clock through std and logs it. The integration test boots this
+# fixture under a pinned clock override and asserts the logged time matches
+# the override, proving the guest observes virtualized time end to end.
+
+[module]
+name = "clock-reader"
+version = "0.1.0"
+component = "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+
+[capabilities]
+required = ["logging"]
+optional = []
+
+[capabilities.http]
+allow = []
+
+[[subscription]]
+kind = "block"
+chain_id = 1

modules/fixtures/clock-reader/module.toml

@@ -0,0 +1,53 @@
+//! # clock-reader (test fixture)
+//!
+//! On every event reads `std::time::SystemTime::now()` and logs the wall
+//! time as whole seconds since the Unix epoch. Under `wasm32-wasip2` that
+//! read routes to `wasi:clocks/wall-clock`, which the supervisor
+//! virtualizes per store, so a test that boots this fixture under a pinned
+//! clock override can assert from the log line that the guest observed the
+//! overridden time rather than the ambient host clock.
+//!
+//! Not a production module. Lives under `modules/fixtures/` so it is
+//! obviously test-only and never gets loaded by the testnet configs.
+
+#![cfg_attr(not(test), warn(unused_crate_dependencies))]
+#![allow(clippy::too_many_arguments)]
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+wit_bindgen::generate!({
+    path: [
+        "../../../wit/nexum-value-flow",
+        "../../../wit/nexum-intent",
+        "../../../wit/nexum-host",
+    ],
+    world: "nexum:host/event-module",
+    generate_all,
+});
+
+use nexum::host::{logging, types};
+
+struct ClockReader;
+
+impl Guest for ClockReader {
+    fn init(_config: Vec<(String, String)>) -> Result<(), Fault> {
+        // Minimal SDK-free fixture: no tracing subscriber is installed,
+        // so log through the raw host binding directly.
+        logging::log(logging::Level::Info, "clock-reader init");
+        Ok(())
+    }
+
+    fn on_event(_event: types::Event) -> Result<(), Fault> {
+        // Whole seconds since the epoch is parseable and stable: the
+        // override pins wall time to an exact instant, so the guest reads
+        // that instant back rather than the ambient host clock.
+        let secs = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map(|d| d.as_secs())
+            .unwrap_or(0);
+        logging::log(logging::Level::Info, &format!("clock wall {secs}"));
+        Ok(())
+    }
+}
+
+export!(ClockReader);