viobench 0.0.1__py3-none-any.whl

viobench/__init__.py

@@ -0,0 +1,26 @@
+"""viobench: compute-aware relative state estimation challenge.
+
+Two halves, split at the WebAssembly boundary:
+- `viobench.tools`    host side — runs, scores, serves: `abi` (the contract), `datasets`, `runner`, `server`, `cli`.
+- `viobench.solution` guest side — how a solution .wasm is built: toolchain, runtime/{native,python}, examples.
+                     Mostly files, not modules; the Python runtime's bundler is the one importable piece.
+
+`import viobench` gives the host-side essentials: Engine, Sandbox, Limits, StepResult, Episode, read_episode, evaluate.
+"""
+from .tools import abi
+from .tools.runner.engine import Engine
+from .tools.runner.sandbox import Limits, Sandbox, SandboxError, SandboxTrap, StepResult
+
+__all__ = ["abi", "Engine", "Limits", "Sandbox", "SandboxError", "SandboxTrap", "StepResult", "Episode", "read_episode", "evaluate"]
+
+
+def __getattr__(name):  # heavier optional dependencies (cv2, yaml) load on first use
+    if name in ("Episode", "read_episode"):
+        from .tools import datasets
+
+        return getattr(datasets, name)
+    if name == "evaluate":
+        from .tools.runner.run import evaluate
+
+        return evaluate
+    raise AttributeError(name)

viobench/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .tools.cli import main
+
+sys.exit(main())

viobench/solution/examples/native/cpp_minimal/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.20)
+project(solution C CXX)
+# wasm (the submission): viobench bundle <this directory> -o solution.wasm
+# host debug build:      cmake -S . -B build-host && cmake --build build-host && build-host/debug <feed dir>   (docs/DEBUGGING.md)
+set(CMAKE_CXX_STANDARD 17)
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release)
+endif()
+set(VIOBENCH_NATIVE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../runtime/native" CACHE PATH "directory with viobench_abi.h and viobench_reactor.cmake")
+include(${VIOBENCH_NATIVE_DIR}/viobench_reactor.cmake)
+viobench_solution(solution solution.cpp)
+target_compile_options(solution PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>)

viobench/solution/examples/native/cpp_minimal/README.md

@@ -0,0 +1,10 @@
+# cpp_minimal
+
+The ABI in C++ without the Python runtime: about 40 KB, a few thousand fuel units of overhead per step.
+
+```bash
+viobench bundle <this directory> -o solution.wasm
+viobench check solution.wasm
+```
+
+Building, debugging on the host, OpenCV and Rust: `runtime/native/README.md` in the workspace.

viobench/solution/examples/native/cpp_minimal/solution.cpp

@@ -0,0 +1,97 @@
+// Minimal native solution: a wasm32-wasip1 reactor implementing the viobench ABI (runtime/native/viobench_abi.h) without
+// Python. It reports the identity pose and a zero twist and shows where to put state and how to read the config.
+// Build:  viobench bundle <this directory> -o solution.wasm
+#include "viobench_abi.h"
+
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <vector>
+
+namespace {
+
+
+struct Config {
+    int width = 0, height = 0;
+    double fx = 0, fy = 0, cx = 0, cy = 0;
+};
+
+// A deliberately tiny JSON number lookup: finds `"key": <number>`. Good enough for the flat config's scalars; use a
+// real JSON parser (e.g. nlohmann/json, header-only, works with wasi-sdk) for T_cam_imu.
+bool find_number(const std::string& json, const char* key, double& out) {
+    std::string needle = std::string("\"") + key + "\"";
+    size_t at = json.find(needle);
+    if (at == std::string::npos) return false;
+    at = json.find(':', at + needle.size());
+    if (at == std::string::npos) return false;
+    out = std::strtod(json.c_str() + at + 1, nullptr);
+    return true;
+}
+
+struct State {
+    Config config;
+    long frames = 0;
+    std::vector<uint8_t> previous_frame;  // keep the previous frame: the host reuses its buffer every step
+    double position[3] = {0, 0, 0};
+    double quaternion[4] = {0, 0, 0, 1};  // x, y, z, w
+    double velocity[3] = {0, 0, 0};       // of the camera centre, in camera axes
+    double angular_velocity[3] = {0, 0, 0};  // in camera axes
+};
+
+State state;
+
+}  // namespace
+
+int32_t abi_version() { return VIOBENCH_ABI_VERSION; }
+
+void* alloc(uint32_t size) { return std::malloc(size ? size : 1); }
+
+// Optional (320 is the default without it); return 640 for 640x480 frames. Called once, before init().
+int32_t frame_width() { return 320; }
+
+// Called once per instance; step() is only called after init() succeeded.
+int32_t init(const char* json, uint32_t length) {
+    std::setvbuf(stdout, nullptr, _IONBF, 0);  // a reactor never exits: unbuffered prints reach the host log
+    std::setvbuf(stderr, nullptr, _IONBF, 0);
+    std::string text(json, length);
+    double value;
+    if (find_number(text, "width", value)) state.config.width = static_cast<int>(value);
+    if (find_number(text, "height", value)) state.config.height = static_cast<int>(value);
+    find_number(text, "fx", state.config.fx);
+    find_number(text, "fy", state.config.fy);
+    find_number(text, "cx", state.config.cx);
+    find_number(text, "cy", state.config.cy);
+    if (state.config.width <= 0 || state.config.height <= 0) {
+        std::fprintf(stderr, "config without image size\n");
+        return VIOBENCH_STATUS_ERROR;
+    }
+    state.previous_frame.resize(static_cast<size_t>(state.config.width) * state.config.height * 3);  // RGB
+    std::printf("init: %dx%d fx=%.1f cx=%.1f\n", state.config.width, state.config.height, state.config.fx, state.config.cx);
+    return VIOBENCH_STATUS_OK;
+}
+
+// frame: height*width*3 uint8 RGB; imu: imu_count rows [t, ax, ay, az, gx, gy, gz];
+// out: [x, y, z, qx, qy, qz, qw, vx, vy, vz, wx, wy, wz] (all 13 values, every step)
+int32_t step(double t, const uint8_t* frame, const double* imu, int32_t imu_count, double* out) {
+    state.frames++;
+    double mean = 0;
+    for (size_t i = 0; i < state.previous_frame.size(); i++) mean += frame[i];
+    mean /= static_cast<double>(state.previous_frame.size());
+    double gyro_norm = 0;
+    for (int32_t i = 0; i < imu_count; i++) {
+        const double* row = imu + 7 * i;
+        gyro_norm += std::sqrt(row[4] * row[4] + row[5] * row[5] + row[6] * row[6]);
+    }
+    if (state.frames == 1) std::printf("first frame t=%.3f mean=%.1f imu rows=%d\n", t, mean, imu_count);
+    std::memcpy(state.previous_frame.data(), frame, state.previous_frame.size());
+    // identity pose, standing still: replace with your estimate of the current camera frame in the first camera frame
+    // and of its twist
+    for (int i = 0; i < 3; i++) out[i] = state.position[i];
+    for (int i = 0; i < 4; i++) out[3 + i] = state.quaternion[i];
+    for (int i = 0; i < 3; i++) out[7 + i] = state.velocity[i];
+    for (int i = 0; i < 3; i++) out[10 + i] = state.angular_velocity[i];
+    return VIOBENCH_STATUS_OK;
+}

viobench/solution/examples/python/minimal/solution.py

@@ -0,0 +1,29 @@
+"""The smallest valid solution: reports the identity pose and a zero twist (standing still) for every frame.
+
+Use it as the template for your own (`viobench init python <dir>` starts a workspace with it): keep the class name
+`Solution`, the constructor signature and `step`.
+Bundle and check it with
+    viobench bundle <this directory> -o solution.wasm
+    viobench check solution.wasm
+"""
+import numpy as np
+
+
+class Solution:
+    frame_width = 320  # optional (320 is the default); 640 asks for 640x480 frames
+
+    def __init__(self, config):
+        # config: frame size, intrinsics, camera-IMU extrinsics (docs/ABI.md)
+        self.config = config
+        self.frames = 0
+
+    def step(self, t, frame, imu):
+        """t: frame timestamp [s]; frame: uint8 (H, W, 3) RGB, read-only view valid until the next step;
+        imu: float64 (N, 7) rows [t, ax, ay, az, gx, gy, gz] with t_prev < t <= t_frame.
+        Return 13 values for every frame: [x, y, z, qx, qy, qz, qw], the pose of this camera frame in the frame of the
+        first one, then [vx, vy, vz, wx, wy, wz], the velocity of the camera centre and the angular velocity, both in
+        this camera frame's axes."""
+        if self.frames == 0:
+            print(f"first frame at t={t:.3f}s shape={frame.shape} dtype={frame.dtype} imu rows={len(imu)}")
+        self.frames += 1
+        return np.array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])

viobench/solution/runtime/native/README.md

@@ -0,0 +1,22 @@
+# Native solutions (C, C++, Rust)
+
+Implement the exports of `viobench_abi.h` (`docs/ABI.md`). Start from `viobench init native <workspace>` (the
+`examples/native/cpp_minimal` example as `solution/`); its `CMakeLists.txt` needs only
+`include(${VIOBENCH_NATIVE_DIR}/viobench_reactor.cmake)` and `viobench_solution(<target> <sources...>)`.
+
+```bash
+viobench bundle <dir> -o solution.wasm   # runtime/native/build.sh: wasi-sdk (fetched into the workspace's build/toolchain) → <dir>/build/, copied to -o
+viobench check solution.wasm
+```
+
+The same CMake call configured with the host compiler builds `build-host/debug` (`docs/DEBUGGING.md`).
+
+- `exit()`, `abort()` and uncaught C++ exceptions trap: return `-1` instead. Make stdout and stderr unbuffered; a
+  reactor never exits.
+- **Other libraries**: cross-build them with the workspace's `build/toolchain/wasi-sdk` (fetch their sources in
+  `toolchain/download_dependencies.sh` if you like) and link them in your `CMakeLists.txt`.
+- **OpenCV**: the Python runtime build leaves static libraries and headers in `build/runtime/opencv-build`. Compile
+  with `-fwasm-exceptions -mllvm -wasm-use-legacy-eh=false`; link with `-fwasm-exceptions -lc++ -lc++abi -lunwind`.
+  `viobench/solution/examples/native/openvins` does this and ports a larger C++ project (OpenVINS, Ceres, Eigen).
+- **Rust**: `crate-type = ["cdylib"]`, target `wasm32-wasip1`, `#[no_mangle] pub extern "C" fn step(t: f64, frame:
+  *const u8, imu: *const f64, n: i32, out: *mut f64) -> i32` and the other exports.

viobench/solution/runtime/native/build.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Builds a native (C/C++) solution directory with wasi-sdk (`viobench bundle <dir> -o x.wasm` runs this):  runtime/native/build.sh <dir> [cmake arguments]
+# The directory needs a CMakeLists.txt (see examples/native/cpp_minimal); the module lands in <dir>/build/<target>.wasm.
+# wasi-sdk comes from the workspace's build/toolchain (toolchain/download_dependencies.sh native, run here first).
+set -euo pipefail
+if [ $# -lt 1 ]; then
+    echo "usage: $0 <solution directory> [extra cmake arguments]" >&2
+    exit 2
+fi
+HERE=$(cd "$(dirname "$0")" && pwd)
+TOOLCHAIN=${TOOLCHAIN:-$HERE/../../build/toolchain}
+SOLUTION=$(cd "$1" && pwd)
+shift
+bash "$HERE/../../toolchain/download_dependencies.sh" native
+mkdir -p "$SOLUTION/build"
+cmake -S "$SOLUTION" -B "$SOLUTION/build" -DCMAKE_TOOLCHAIN_FILE="$TOOLCHAIN/wasi-sdk/share/cmake/wasi-sdk-p1.cmake" -DVIOBENCH_NATIVE_DIR="$HERE" "$@" > "$SOLUTION/build/cmake.log" 2>&1 || (cat "$SOLUTION/build/cmake.log"; exit 1)
+cmake --build "$SOLUTION/build"
+ls -la "$SOLUTION"/build/*.wasm

viobench/solution/runtime/native/viobench_abi.h

@@ -0,0 +1,51 @@
+/* viobench solution ABI, version 1 (docs/ABI.md) — the whole contract between a solution module and the harness.
+ *
+ * A solution is a wasm32-wasip1 *reactor* that exports the functions declared below (plus `memory`). The harness
+ * calls, per episode: _initialize (if present) -> frame_width (if present) -> init(config_json) -> alloc x3 -> step(...) x N.
+ * Anything may run inside; this header is a convenience for C/C++ solutions, the Python runtime
+ * (viobench/solution/runtime/python/reactor.c) uses it too, so status codes exist in exactly one place.
+ */
+#ifndef VIOBENCH_ABI_H
+#define VIOBENCH_ABI_H
+
+#include <stdint.h>
+
+#define VIOBENCH_ABI_VERSION 1
+
+/* Mark a function as a wasm export under its own name (a no-op in a host debug build). */
+#if defined(__wasm__)
+#define VIOBENCH_EXPORT(name) __attribute__((export_name(#name)))
+#else
+#define VIOBENCH_EXPORT(name)
+#endif
+
+/* Buffer layouts: everything little-endian; pointers are offsets into the module's linear memory. */
+#define VIOBENCH_IMU_ROW_VALUES 7 /* [t_s, ax, ay, az, gx, gy, gz] as double */
+#define VIOBENCH_POSE_VALUES 7    /* [x, y, z, qx, qy, qz, qw] as double, camera k in camera 0 */
+#define VIOBENCH_TWIST_VALUES 6   /* [vx, vy, vz, wx, wy, wz] as double, velocity and angular velocity of camera k in its own axes */
+#define VIOBENCH_STATE_VALUES 13  /* out[]: the pose, then the twist */
+
+/* Status codes returned by init() and step(): anything but OK is an error (explain it on stderr). */
+#define VIOBENCH_STATUS_OK 0     /* init: ready; step: out[] holds the pose and the twist */
+#define VIOBENCH_STATUS_ERROR -1 /* the episode ends and is marked failed */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Exports every solution must provide (`memory` is exported by the toolchain automatically). */
+VIOBENCH_EXPORT(abi_version) int32_t abi_version(void);                   /* returns VIOBENCH_ABI_VERSION */
+VIOBENCH_EXPORT(alloc) void *alloc(uint32_t size);                        /* malloc; never freed by the host */
+VIOBENCH_EXPORT(frame_width) int32_t frame_width(void);                  /* optional: 320 (the default without it) or 640 (640x480) */
+VIOBENCH_EXPORT(init) int32_t init(const char *config_json, uint32_t length); /* once; the bytes are valid during the call */
+VIOBENCH_EXPORT(step) int32_t step(double t, const uint8_t *frame, const double *imu, int32_t imu_count, double *out);
+/* frame: height*width*3 uint8 RGB (row-major), size per the config; imu: imu_count (always 10) rows of VIOBENCH_IMU_ROW_VALUES
+ * doubles with t_prev_frame < t <= t_frame; out: VIOBENCH_STATE_VALUES doubles, all written on VIOBENCH_STATUS_OK (the host fills
+ * them with NaN before the call, so a value left out fails the step). The frame and IMU buffers are reused for the next
+ * step: copy what you want to keep. */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* VIOBENCH_ABI_H */

viobench/solution/runtime/native/viobench_debug_main.c

@@ -0,0 +1,136 @@
+/* Host-side driver for debugging a native solution outside the wasm sandbox.
+ *
+ * Linked with your solution's sources by viobench_reactor.cmake whenever the configure is not WASI
+ * (`cmake -S . -B build-host && cmake --build build-host` -> build-host/debug). It reads a feed directory written by
+ * `viobench feed <episode> -o <dir>` (raw arrays, no PNG/JSON parsing needed), calls init() and step() exactly like the
+ * sandbox would, writes estimate.tum and twist.txt next to it and prints the position RMSE. Score it fully with
+ * `viobench score <episode> estimate.tum`.
+ * Run under gdb/lldb:  gdb --args build-host/debug <feed dir>
+ */
+#include "viobench_abi.h"
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+#define TIME_TOLERANCE 1e-6 /* seconds: the same slack the host harness uses when selecting IMU rows */
+
+/* The harness's test for a usable state (pose and twist): all finite, with a non-zero quaternion. */
+static int usable(const double *state) {
+    for (int i = 0; i < VIOBENCH_STATE_VALUES; i++) {
+        if (!isfinite(state[i])) return 0;
+    }
+    return state[3] != 0 || state[4] != 0 || state[5] != 0 || state[6] != 0;
+}
+
+static void *read_file(const char *directory, const char *name, size_t *size) {
+    char path[4096];
+    snprintf(path, sizeof path, "%s/%s", directory, name);
+    FILE *file = fopen(path, "rb");
+    if (file == NULL) {
+        fprintf(stderr, "cannot open %s\n", path);
+        exit(2);
+    }
+    fseek(file, 0, SEEK_END);
+    long length = ftell(file);
+    fseek(file, 0, SEEK_SET);
+    void *data = malloc((size_t)length + 1);
+    if (fread(data, 1, (size_t)length, file) != (size_t)length) {
+        fprintf(stderr, "short read on %s\n", path);
+        exit(2);
+    }
+    ((char *)data)[length] = 0;
+    fclose(file);
+    *size = (size_t)length;
+    return data;
+}
+
+static double now_seconds(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (double)ts.tv_sec + 1e-9 * (double)ts.tv_nsec;
+}
+
+int main(int argc, char **argv) {
+    if (argc < 2) {
+        fprintf(stderr, "usage: %s <feed directory from `viobench feed`> [estimate.tum]\n", argv[0]);
+        return 2;
+    }
+    const char *directory = argv[1];
+    const char *output = argc > 2 ? argv[2] : "estimate.tum";
+
+    size_t size;
+    char *shape = read_file(directory, "shape.txt", &size);
+    long frames, height, width, channels, imu_rows;
+    if (sscanf(shape, "%ld %ld %ld %ld %ld", &frames, &height, &width, &channels, &imu_rows) != 5) {
+        fprintf(stderr, "bad shape.txt\n");
+        return 2;
+    }
+    char *config = read_file(directory, "config.json", &size);
+    size_t config_length = size;
+    size_t frame_bytes = (size_t)height * (size_t)width * (size_t)channels;
+    uint8_t *pixels = read_file(directory, "frames.u8", &size);
+    if (size != frame_bytes * (size_t)frames) {
+        fprintf(stderr, "frames.u8 has %zu bytes, expected %zu\n", size, frame_bytes * (size_t)frames);
+        return 2;
+    }
+    double *frame_times = read_file(directory, "frame_times.f64", &size);
+    double *imu = read_file(directory, "imu.f64", &size);
+    double *ground_truth = read_file(directory, "gt.f64", &size);
+
+    printf("feed: %ld frames %ldx%ldx%ld, %ld IMU rows, abi %d\n", frames, width, height, channels, imu_rows, abi_version());
+    int32_t status = init(config, (uint32_t)config_length);
+    if (status != VIOBENCH_STATUS_OK) {
+        fprintf(stderr, "init returned %d\n", status);
+        return 1;
+    }
+
+    char twist_output[4096]; /* twist.txt next to the pose file */
+    const char *slash = strrchr(output, '/');
+    snprintf(twist_output, sizeof twist_output, "%.*stwist.txt", slash ? (int)(slash - output + 1) : 0, output);
+    FILE *tum = fopen(output, "w");
+    FILE *twist = fopen(twist_output, "w");
+    if (tum == NULL || twist == NULL) {
+        fprintf(stderr, "cannot write %s\n", tum == NULL ? output : twist_output);
+        return 2;
+    }
+    fprintf(tum, "# t x y z qx qy qz qw (camera k in camera 0 frame)\n");
+    fprintf(twist, "# t vx vy vz wx wy wz (velocity and angular velocity of camera k in camera k axes)\n");
+    double state[VIOBENCH_STATE_VALUES];
+    double previous = -INFINITY;
+    long window_start = 0;
+    long k = 0;
+    double squared_error = 0.0, total_seconds = 0.0;
+    for (; k < frames; k++) {
+        double t = frame_times[k];
+        /* IMU rows with t_prev < t_row <= t (the feed starts at frame 0's window, so frame 0 gets everything up to its own time) */
+        while (window_start < imu_rows && imu[window_start * VIOBENCH_IMU_ROW_VALUES] <= previous + TIME_TOLERANCE) window_start++;
+        long window_end = window_start;
+        while (window_end < imu_rows && imu[window_end * VIOBENCH_IMU_ROW_VALUES] <= t + TIME_TOLERANCE) window_end++;
+        for (int i = 0; i < VIOBENCH_STATE_VALUES; i++) state[i] = NAN; /* like the host: a value not written fails the step */
+        double started = now_seconds();
+        status = step(t, pixels + (size_t)k * frame_bytes, imu + window_start * VIOBENCH_IMU_ROW_VALUES, (int32_t)(window_end - window_start), state);
+        double seconds = now_seconds() - started;
+        if (status != VIOBENCH_STATUS_OK || !usable(state)) {
+            printf("frame %ld: %s; the harness ends the episode here and marks it failed\n", k,
+                   status != VIOBENCH_STATUS_OK ? "step returned an error"
+                                               : "state not usable (not all 13 values written, NaN/inf, or all-zero quaternion)");
+            break;
+        }
+        total_seconds += seconds;
+        fprintf(tum, "%.9g %.9g %.9g %.9g %.9g %.9g %.9g %.9g\n", t, state[0], state[1], state[2], state[3], state[4], state[5], state[6]);
+        fprintf(twist, "%.9g %.9g %.9g %.9g %.9g %.9g %.9g\n", t, state[7], state[8], state[9], state[10], state[11], state[12]);
+        const double *truth = ground_truth + k * VIOBENCH_POSE_VALUES;
+        double dx = state[0] - truth[0], dy = state[1] - truth[1], dz = state[2] - truth[2];
+        squared_error += dx * dx + dy * dy + dz * dz;
+        previous = t;
+        window_start = window_end;
+    }
+    fclose(tum);
+    fclose(twist);
+    printf("%ld/%ld frames ok, position RMSE over them %.3f m, %.2f ms/frame (host, no fuel); poses in %s, twists in %s\n", k, frames,
+           sqrt(squared_error / (double)k), 1e3 * total_seconds / (double)k, output, twist_output);
+    return k < frames;
+}

viobench/solution/runtime/native/viobench_reactor.cmake

@@ -0,0 +1,24 @@
+# viobench_solution(<target> <sources...>)  — one call, two builds:
+#   * configured with the wasi-sdk toolchain file (viobench bundle does that):
+#     the solution reactor <target>.wasm that you submit;
+#   * configured with your host compiler (`cmake -S . -B build-host && cmake --build build-host`): an executable
+#     `debug` = your sources + viobench_debug_main.c, built with -g, that reads a feed from `viobench feed` and calls your
+#     init()/step() exactly like the sandbox — for gdb/lldb/VS Code.
+function(viobench_solution target)
+    set(sources ${ARGN})
+    if(CMAKE_SYSTEM_NAME STREQUAL "WASI")
+        add_executable(${target} ${sources})
+        target_include_directories(${target} PRIVATE ${CMAKE_CURRENT_FUNCTION_LIST_DIR})
+        target_compile_options(${target} PRIVATE -O2 -msimd128)
+        # a reactor: no main(), the VIOBENCH_EXPORT functions are the entry points; 64 MiB initial memory avoids early grows
+        target_link_options(${target} PRIVATE -mexec-model=reactor -Wl,--initial-memory=67108864 -Wl,--strip-debug)
+        set_target_properties(${target} PROPERTIES SUFFIX ".wasm")
+    else()
+        enable_language(C)
+        add_executable(${target} ${sources} ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/viobench_debug_main.c)
+        target_include_directories(${target} PRIVATE ${CMAKE_CURRENT_FUNCTION_LIST_DIR})
+        target_compile_options(${target} PRIVATE -g -O1)
+        set_target_properties(${target} PROPERTIES OUTPUT_NAME debug)
+        message(STATUS "viobench: host configure -> building the `debug` driver (not a submission); use viobench bundle for the .wasm")
+    endif()
+endfunction()

viobench/solution/runtime/python/README.md

@@ -0,0 +1,55 @@
+# The Python runtime: build
+
+`build.sh` (what `viobench build-runtime` runs: `toolchain/download_dependencies.sh`, then `cpython/build-wasm.sh`;
+10–15 min) writes two modules to the workspace's `build/runtime/dist/`:
+
+- `runtime.wasm`: CPython 3.14.4, numpy 2.3.4 and OpenCV 4.12.0 as a reactor implementing `docs/ABI.md`;
+- `python.wasm`: the same as a command-line interpreter.
+
+Both are single-threaded and need no directory: the stdlib and numpy's Python code are frozen in. OpenCV uses SIMD128
+and wasm exceptions (wasi-sdk 34 `eh` runtime, Wasmtime ≥ 50).
+
+```bash
+runtime/python/build.sh                 # or viobench build-runtime
+runtime/python/cpython/test.sh          # numpy's tests inside python.wasm
+runtime/python/cpython/python.sh        # a REPL
+```
+
+Pure-Python packages need no rebuild: copy them into your solution directory. Extension modules are cross-built in
+`cpython/build-wasm.sh` and linked in like numpy and OpenCV (below).
+
+| file | role |
+|---|---|
+| `reactor.c` | the ABI exports (with `../native/viobench_abi.h`) and the 32-byte bundle descriptor that `viobench bundle` patches |
+| `guest/viobench_guest.py` | frozen shim: imports the bundle, loads `Solution`, glues `step` |
+| `cpython/build-wasm.sh`, `patches/`, `scripts/` | the cross-build |
+
+Overrides (paths in the workspace): `TOOLCHAIN` (default `build/toolchain`), `SRC` (pristine sources), `WASI_SDK_PATH`, `VENV`, `WASMTIME`,
+`BUILD` (default `build/runtime`). The patched sources in `build/runtime/src` are plain copies:
+`diff -ru build/toolchain/src/numpy build/runtime/src/numpy` shows the changes; delete `build/runtime/src/<project>`
+after editing a patch.
+
+## How it links
+
+- WASI has no dynamic loading. `scripts/collect_numpy.py` archives each extension module's objects, and
+  `scripts/link.py` links them into CPython with a generated `main.c` that registers each module in the inittab under
+  its dotted name (`numpy._core._multiarray_umath`).
+- `scripts/freeze.py` compiles the `.py` files into one blob, embedded with `#embed` and installed as
+  `PyImport_FrozenModules`. Tracebacks show files and lines but no source.
+- `link.py --reactor reactor.c` links with `-mexec-model=reactor`: `_initialize` runs the C++ static constructors, and
+  `reactor.c` starts the interpreter in its `frame_width` export (isolated config, unbuffered stdio, fixed hash seed).
+
+| patch | reason |
+|---|---|
+| numpy `npy_cpu.h` | wasm CPU detection only under Emscripten |
+| numpy `random/meson.build`, `static_link_rename.h` | `mtrand`'s copy of `distributions.c` collides with the other once linked into one binary |
+| OpenCV `cv_cpu_dispatch.h`, `intrin_wasm.hpp` | wasm SIMD gated on Emscripten |
+| OpenCV `stereo_geom.cpp`, `cv2.cpp` | missing `<iterator>` with libc++ 23 |
+
+Left out: the `zlib`, `bz2`, `lzma`, `ssl`, `ctypes`, `sqlite3` modules; stdlib `test`, `idlelib`, `tkinter`,
+`ensurepip`, `venv`, `pydoc_data`; numpy `tests`, `f2py`; OpenCV `imgcodecs`, `highgui`, `objdetect`. `dnn` needs
+`BUILD_opencv_dnn=ON` explicitly (thread support is disabled). numpy never warns on overflow or invalid values (wasm
+has no floating-point flags), and its default integer is 32-bit.
+
+Compile `.cwasm` files on the machine that runs them, and never accept them from others: `--allow-precompiled` skips
+validation.

viobench/solution/runtime/python/build.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Builds the reference Python runtime (CPython + numpy + OpenCV as a wasip1 reactor) natively on Linux or macOS (Windows: inside WSL2).
+# Output in the workspace's build/runtime/dist: runtime.wasm (what `viobench bundle` embeds your code into; `viobench build-runtime`
+# runs this script, and `viobench bundle` does when runtime.wasm is missing) and python.wasm (a REPL for experiments).
+# First build 10-15 minutes; fetches the toolchain into build/toolchain first (toolchain/download_dependencies.sh). Run from anywhere.
+set -euo pipefail
+HERE=$(cd "$(dirname "$0")" && pwd)
+bash "$HERE/../../toolchain/download_dependencies.sh"
+bash "$HERE/cpython/build-wasm.sh" "$@"

viobench/solution/runtime/python/bundler/__init__.py

@@ -0,0 +1,10 @@
+"""The Python runtime's packaging step: a solution directory -> one self-contained solution.wasm, and back.
+
+`viobench bundle <dir> -o x.wasm` zips the directory and embeds it into runtime.wasm as a data segment (`embed`);
+`viobench unbundle` extracts it. Depends only on the contract (viobench.tools.abi) and the workspaces (viobench.solution.workspace); the runner never
+imports this.
+"""
+
+
+class BundleError(Exception):
+    """Invalid solution directory or runtime binary."""