wysm

the WASM runtime tier of soft3 — cyber's name for the wasm sandbox layer. a hard fork of wasmi v2.0.0-beta.2, extended with four cyber-native enhancements: jet substitution, finite-style metering, an actor harness, and a trident-lowering on-ramp. the runtime cyb embeds to execute conventional programs (souls) loaded from radio, sandboxed and resource-bounded, with a migration path to provable nox execution.

naming

wysm is cyber's name for the runtime. wasm and WASM refer to the WebAssembly format and ecosystem. wasmi is the upstream project this fork tracks. cyber-side crates use the wysm- prefix (wysm-jet, wysm-meter, wysm-harness, wysm-trident); upstream crates keep their wasmi_* names to remain mergeable.

position in soft3

wasm is the seat for conventional programs — anything that compiles to WebAssembly, deployed as a particle, executed as a soul. its proof contract is the weakest of the four runtimes: a host call returns a noun, the noun is recorded as a witness in the calling rune program, the surrounding pure computation is provable conditional on that witness. wasm itself carries no Nox trace. this is the price of accepting conventional programs.

the long-term arc is migration: WASM → trident LIR → Nox (with zheng proof). wasm is the soft path; nox is the hard one. souls start in wasm and graduate to nox over time as their inner loops get lowered through trident.

fork rationale

wasmi is consumed as a fork, not a dependency, because cyb does substantive work on the runtime itself:

1. jet substitution is a new subsystem. it lives below wasmi::engine::executor and must intercept dispatch — not bolt-on after-the-fact. cleanest as an internal crate, not a wrapping layer.
2. metering is module-rewrite-time instrumentation (NEAR finite-wasm model). it sits between wasmparser and wasmi::Module::new. wrapping doesn't compose well; folding into the loader does.
3. harness ports lunatic's actor/mailbox/capability-token patterns onto wasmi. lunatic itself hard-codes wasmtime. the port lives best as cyber's own code with wasmi-as-engine, not as a fork of lunatic.
4. trident lowering reads wasmi's IR (the new wasmi_ir 3.0 crate, public types) and emits trident LIR. tightly coupled to wasmi internals — must move with them.

upstream wasmi is small, audited (SRLabs 2023, Runtime Verification 2024), and on a roughly-quarterly release cadence. the fork commits to merging upstream every release. divergence is intentional but bounded: cyber-specific code lives in new crates (wysm-jet, wysm-meter, wysm-harness, wysm-trident); upstream crates are touched only when the dispatch loop needs a jet hook or the loader needs a metering hook. patches are tracked in specs/patches.md.

base — wasmi v2.0.0-beta.2

forked from upstream commit a8f6d806 (2026-03-04). cyber-base branch tracks this commit; upstream is the upstream remote.

what v2 already provides that earlier wasmi did not:

• new internal IR (wasmi_ir 3.0), public Rust types — the foldable surface trident lowering reads from
• tail-call dispatch via Rust become (PR #1655) behind --features unstable. resolves issue #1101. stitch-style threaded code, no fork patch needed.
• portable-dispatch / indirect-dispatch feature flags trading throughput for portability
• rewritten ResourceLimiter (#1817) with cleaner enforcement of trap_on_grow_failure
• sysv64 calling convention on x86_64 (#1792) for execution handlers — better codegen than default Rust ABI
• edition 2024, MSRV 1.86

the cyb build enables unstable by default on tier-1 targets (macOS x86_64/aarch64, Linux x86_64/aarch64, Windows x86_64). portable-dispatch is the fallback for Android and embedded.

four enhancements

1. jet substitution

the cyber-unique contribution. at module load, every function body is normalized (strip locals, alpha-rename, canonicalize block structure) and hashed. the hash is looked up in a global jet table. on hit, the function body is replaced with a host trampoline to a native Rust implementation.

target jet library (in order of expected impact):

the design borrows directly from the nox jet model. jet identity is itself a particle; jets are content-addressable; upgrading a jet produces a new particle and does not invalidate prior compilations. dispatch is structural (hash match) — no source-language assumptions, jets fire whether the module was compiled from Rust, C, Zig, or AssemblyScript.

equivalence is asserted by the jet author and verified by differential testing: the reference wasm function and the native jet are both executed on a corpus; outputs must match for every input. failures are CI errors, not silent fallback. when in doubt, drop the jet — incorrect jets are a soundness hole, not a perf miss.

2. tail-call dispatch — already upstream

shipping in wasmi v2.0.0-beta.2 behind --features unstable. the cyb build enables this by default. stitch-shape threaded code via Rust's become keyword (RFC 2691). measured by upstream: ~2-3× over the match-loop dispatch on Coremark-class workloads, with regressions on some opcode shapes (cf. Pulley issue wasmtime#9995). the fallback portable-dispatch is kept for hosts where become cannot be lowered.

no patch required. the work is testing: benchmark cyb's actual soul workloads against both dispatch modes, ship whichever wins per-arch.

3. metering — finite-wasm pattern

module-rewrite-time deterministic gas instrumentation, modeled on near/finite-wasm. lives in a new crate wysm-meter sitting between wasmparser and wasmi::Module::new.

the rewrite injects:

• per-instruction gas counter decrement (collapsed per basic-block)
• per-instruction stack-depth check (collapsed per function entry)
• a global trap when gas reaches zero

this decouples metering from the engine forever. swapping wasmi → wasmer-singlepass → trident-lowered nox does not require rewriting the gas contract — the metered module carries its own gas semantics.

NEAR (finite-wasm) and DFINITY (IC embedder static instrumentation) independently arrived at the same design — module-rewrite, engine-agnostic, deterministic across nodes. the convergence is the design's validation. see "prior art and borrowed patterns" for the full cross-reference.

4. harness — actor model on wasmi

a port of lunatic's actor patterns onto wasmi, since lunatic itself is welded to wasmtime and stalled since May 2023. the four patterns worth porting:

target LOC: ~3k for the cyb-side implementation. lunatic's design is sound; only the implementation is wasmtime-coupled.

the supervision tree is built on a PausedExecution primitive borrowed from DFINITY's IC embedder: a soul that has paused — by fuel exhaustion, hint yield, or signer prompt — is a first-class state in the supervisor's model, distinct from "running" or "dead". the supervisor can snapshot, replay, or hot-reload paused souls without losing in-flight work. it is the wasm-level primitive that completes rune's solid-state-interpreter model — the kernel function (subject, event) -> (new-subject, effects) was already replayable; PausedExecution makes it physical. ~20 lines of trait definition, re-implemented independently of IC-1.0-licensed code.

async contract — rune hint, not async host

wasmi does not support async host functions. wasmtime does (Func::wrap_async). this is correct as a default — async-from-the-guest is a leaky abstraction (the soul cannot reason about whether the host is awaiting). cyb sidesteps the gap entirely via rune's hint primitive:

=/  data  ~hint:%get-text.cid

the soul yields at hint. the host drives the future. when the IPFS read returns, the runtime resumes the soul with the data in the appropriate subject slot. this is the same async model rune already specifies and is the only model where async semantics are visible to the soul, the host, and the proof witness alike.

the gap-class workaround for non-rune wasm modules that call await directly is tokio::runtime::block_on on a per-soul thread — expensive, bounded, only used for foreign modules that did not author against the hint protocol. document this as an anti-pattern.

sandboxing model

bandwidth is bounded one layer up, at the cyb host shims — not at the WASM engine. the existing cyb ipfs queue (cyb/docs/backend.md) is the chokepoint; per-soul rate limits live there, not in wasm.

trident-lowering on-ramp

wysm-trident reads wasmi_ir 3.0's public types and emits trident LIR. mirrors trident's existing mir2nox.rs (Rust MIR → nox) and compile/wasm.rs (nox → wasm). closes the soft3.md migration loop:

.tri → trident LIR → nox (existing)
.rs.mir.json → trident LIR → nox (existing)
.wasm → wasmi_ir → trident LIR → nox (this work)

phase 0: hand-pick a subset of wasmi-IR ops (i32/i64 arithmetic, locals, calls, no memory). lower to trident LIR. round-trip a few hello-world wasm modules. five tests, modeled on trident/src/compile/wasm.rs's existing five tests.

phase 1: linear memory mapping to nox state slots. control flow lowering (block/loop/br_if to LIR structured control).

phase 2: float and SIMD. these may stay un-lowered indefinitely — if a soul uses floats, it stays in wasm and never graduates to nox.

phase 3: opens — should the lowering pass also do circuit-size-aware optimization, or is that pure trident's job? leans pure trident.

resource model — what each axis means in cyb

cyb caps are signed by the neuron running the soul, not by the soul itself. a soul cannot grant itself more gas; it requests, the neuron approves (or auto-approves under policy). this matches the cybermark ~caps subject slot from rune.md.

companion repos

depends on: wasmi_ir, wasmi_core, wasmi_collections (internal). does not depend on any cyber runtime crate — wasm is a leaf in the dependency graph by design.

consumed by: cyb (binary), rune-interp (host call dispatch), trident (via wysm-trident lowering).

roadmap

estimation per cyber convention: 1 pomodoro = 30 min, 1 session = 6 pomodoros.

total: ~22 sessions for a usable production runtime + first lowering experiment. roughly two months at sustained pace.

prior art and borrowed patterns

three production WASM-on-chain systems run deterministic adversarial WASM at scale. each independently arrived at variants of the same architecture. cyb borrows specific patterns from each.

production parallels

common ground across all three: nobody runs Cranelift on adversarial code. all use singlepass JIT or interpreter. all enforce determinism (floats banned or NaN-canonicalized, threads off, sorted iteration). all use module-rewrite or fuel for metering, never after-the-fact accounting. cyb's wasmi v2 + finite-wasm-style metering + Soroban deterministic profile is the convergent design these three arrived at variants of.

borrowed: Soroban deterministic wasmi config

the most battle-tested deterministic wasmi profile in production. cyb copies it verbatim for proof-relevant souls. source: stellar/rs-soroban-env/soroban-env-host/src/budget/wasmi_helper.rs (Apache-2.0).

this is the "deterministic" profile, used for souls whose execution trace is a proof witness. cyb additionally ships a "permissive" profile that re-enables SIMD and floats for UI/render souls that have no proof contract; the choice is per-soul, declared in particle frontmatter.

vendoring note: the helper config is small (~30 LOC) and stable. literal-copy from stellar/rs-soroban-env/soroban-env-host/src/budget/wasmi_helper.rs into crates/wysm-meter/src/profile.rs, preserve Apache-2.0 attribution in the file header, sync against upstream every Soroban release (they update it for new wasm proposals as the determinism story evolves).

execution profiles — deterministic vs permissive

cyb is a soul runtime, not a generic wasm host. souls choose one of two profiles in .cyb frontmatter:

profile = "deterministic"   # proof-relevant: trace is a witness
profile = "permissive"      # UI/render/inference: result accepted on faith

both profiles deny WASI imports. souls must be linked against cyb-sdk (the cyb host binding set, mirroring soroban-sdk / ic-cdk / cosmwasm-std). a WASI shim layer rewrites common WASI imports (fd_write → console log, clock_time_get → ~now, filesystem ops → deny) at module load — same pattern as DFINITY's ic-wasi-polyfill (community-maintained). this is the second, larger gate on "running random wasm": almost no off-the-shelf .wasm will load without either being recompiled against cyb-sdk or running through the WASI shim.

the honest characterization: cyb runs souls, not random wasm. a soul is a wasm module authored for cyb's host API in a chosen profile. every production wasm embed (Soroban, Spin, IC, wasmCloud) does the same; cyb just makes the boundary explicit.

borrowed: Soroban fuel refill pattern

host pushes fuel into the VM before each call (add_fuel_to_vm) and pulls remainder back on return (return_fuel_to_host). budget is held by the host, not the VM; the VM is a transient fuel-burner. Soroban needed this because wasmi 0.31 made FuelCosts private — they patched it back open in their fork. wasmi v2 keeps these accessors public via --features unstable. integrates with wysm-meter for the metering side.

borrowed: Soroban three-tier storage

souls have three storage classes, not one:

source: Stellar CAP-0066 (Protocol 23, "Whisk"). maps cleanly onto bbg dimensions: persistent → bbg, temporary → in-memory, instance → particle frontmatter. rune's ~mem slot becomes persistent by default; souls opt into temporary or instance tiers via ~caps.

borrowed: DFINITY snapshot-at-await

instead of stackful coroutines (wasmi has no good story for these), commit state at the await point, spin up a fresh instance for the callback, only roll back post-await state on failure. dovetails with rune's hint primitive — hint is already a snapshot point in the semantics. mechanism:

1. soul calls a host import that needs to await (e.g. host.ipfs_read)
2. host enqueues the work, registers a callback (fn pointer + env i32) in the soul's continuation table
3. soul's current state is committed; the wasm instance is torn down
4. when the work completes, a fresh instance is spun up from the snapshot and the callback is dispatched
5. if the callback traps, only post-await state rolls back to the snapshot; pre-await effects stay committed

every hint is an interleaving point — same security footgun as IC ("reentrancy on await"). document this in the soul authoring guide as a load-bearing concern, not a footnote.

borrowed: DFINITY NaN canonicalization

one-line engine config for cross-host determinism. cyb's deterministic profile rejects FP entirely (via Soroban config), so this is subsumed. for the permissive profile (UI souls with floats), enable NaN canonicalization explicitly at the engine level. relevant only because some hosts may emit different NaN bit patterns from the same operation — proof-relevant code must agree bit-exactly.

borrowed: Soroban x-macro host-fn registry

call_macro_with_all_host_functions is Soroban's single source of truth for ~190 host functions: declare once, get zero-cost dispatch + version gating + ABI documentation. cyb's host bindings layer (the existing cyb scripting API from cyb/docs/scripting.md) adopts the same pattern for the rune ↔ wasm shim. one macro invocation replaces hand-maintained dispatch tables in three places (engine glue, guest SDK, version manifest).

deferred: Soroban module cache (CAP-0066)

Stellar's Protocol 23 ("Whisk", September 2025) introduced a module cache: contracts are parsed and translated once per transaction, then reused across every invocation in the same tx. for cyb the analogous unit is "once per neuron session" or "once per soul lifetime". translation is the dominant cost for short host calls. defer until benchmarks show translation as the bottleneck — likely after jets + tail-call land. wasmi v2's lazy compilation already amortizes some of this; the explicit cross-invocation cache is a v2-of-cyb optimization.

key files to study (with line counts)

read these before writing the corresponding cyb-side code. each is the production reference for one pattern. cyb's implementations will look structurally similar — that is the design intent, not a coincidence.

bonus findings worth knowing about

rejected alternatives

reflected here so future contributors do not redebate the choices.

wasmtime as the embedded engine

rejected. ~250k LOC of fork surface against cyber's ~200k-LOC total runtime stack. Cranelift is the right answer for trusted code authored in-house; it is the wrong answer for adversarial souls loaded from radio. cosmwasm pins wasmer-singlepass, NEAR forked wasmer-singlepass, polkadot is leaving wasm for PolkaVM/RISC-V — nobody runs Cranelift on adversarial code. cyb follows the pattern.

wasmer as the embedded engine

rejected. diverged from the WASI component model. the component model is the composition story for cybermark-addressable souls. wasmer trades that for WASIX, which cyb does not need.

WAMR (WebAssembly Micro Runtime)

rejected. best mobile story (iOS/Android NDK clean), but cyb does not target iOS per project policy and Android wasmi works fine. importing ~150k LOC of C to dodge a non-problem is poor trade.

lunatic as the actor harness

rejected as a dependency; adopted as a design source. last release v0.13.2 (May 2023), stalled; code welded to wasmtime via wasmtime::Store<T> everywhere. port the four patterns into our own code over wasmi.

CosmWasm (cosmwasm-vm) as the embedded engine

rejected for the cyb client runtime, retained as conceptual prior art for the dialect ABI. cosmwasm-vm is ~15k LOC and audited, but transitively pulls in wasmer-singlepass (~150k LOC), reintroducing the size problem wasmer was rejected for. the execute/query/instantiate/migrate/sudo contract shape is wrong for cyb souls, which are async UI callbacks — not synchronous request/response. the cw-cyber lineage points back to the go-cyber legacy chain, not toward soft3. borrow the entry-point vocabulary for dialects (instantiate, execute, query, migrate, sudo); do not embed the engine.

DFINITY IC embedder (dfinity/ic/rs/embedders/)

rejected as a code dependency, adopted as a design source (see "prior art and borrowed patterns"). the IC-1.0 license grants only extend to code "running directly on the Internet Computer platform"; cyb is outside scope. additionally, the embedder is welded to wasmtime (~250k LOC), the same size problem we rejected at the engine layer. four patterns borrowed independently: PausedExecution, snapshot-at-await, NaN canonicalization, and static bytecode metering — the last of which validates our finite-wasm choice, since DFINITY and NEAR independently arrived at the same metering design.

soroban-wasmi fork (stellar/wasmi)

deferred. Stellar's fork is 7 patches on top of upstream wasmi v0.31.1 (stack-machine era) — crate rename, custom-section exposure, FuelCosts accessors, an InstanceCache bugfix, version bump. cyb runs on v2.0.0-beta.2 (register-machine, ~2-4× faster, lazy compile, Stellar-funded Runtime Verification audit). Soroban stays on 0.31 only because of cost-model recalibration risk; cyb has no such anchor. revisit if specific Soroban patches prove useful — both custom-section exposure and FuelCosts accessors are already public in wasmi v2 via --features unstable.

copy-and-patch compilation (Xu & Kjolstad, OOPSLA '21)

deferred. the algorithm works (Stanford wasm prototype hit 39–63% over Liftoff with ~3-5k LOC runtime), but the org-level integration cost (stencil pipeline, Clang-as-library, W^X policy, three-arch debugging) is heavy for a small team. CPython's 30-month CAP-JIT experience is sobering — at parity or slower with the interpreter after sustained effort. revisit only after jets+tail-call land and we have telemetry on what's left slow.

PolkaVM (wasm → RISC-V)

deferred. PolkaVM is fast and small (~25k LOC, ~0.9× Cranelift), but there is no wasm-to-RISC-V frontend; building it is a year of work. Parity left wasm for RISC-V entirely (pallet-revive). revisit if cyb decides to leave WebAssembly as the input format.

LuaJIT-style tracing JIT

rejected. tracing JIT on wasm was tried in the V8 era and abandoned. wasm control flow is already structured — traces over-specialize and lose to baseline.

neural compilation directly on wasm IR

deferred. trident's GNN+Transformer optimizer is sized for register IR. retraining on wasm stack-IR requires lifting to local-SSA first, plus a (input, faster-equivalent) corpus that does not yet exist. the cleaner neural path is wasm → trident LIR → existing trident neural optimizer, which is the on-ramp we're already building. parallel pursuit, not a replacement.

do not touch zones

cyber-specific code lives in new crates: crates/wysm-jet, crates/wysm-meter, crates/wysm-harness, crates/wysm-trident. additions to these are free.

Kelvin discipline

wasm-K140 (working spec, mutations expected). the runtime is not protocol-critical — souls run locally per neuron, not in consensus. no need to freeze the spec. upstream wasmi follows its own semver; we track its releases.

discover all concepts