Koder Kwasm
- Area: Foundation (Engines / Lang)
- Path:
engines/lang/kwasm - Kind: Self-hosted, embeddable WebAssembly runtime (import + execute)
- Registry:
self-hosted-pairs.mdrow 22 — replaces wazero / wasmtime / wasmer / wasmedge - Status: bootstrapping — full pipeline (decode+SIMD / validate / execute / embed / WASI) done; first consumer (Jet wasm middleware) flipped onto kwasm (self-hosted g4_capability met)
Role in the stack
kwasm runs WebAssembly outside a browser/V8 context — the cases where there is no V8 to lean on: plugin/extension sandboxes, Koder Hub wasm packages, untrusted code execution (services/ai/sandbox), and edge/serverless functions.
It is explicitly not a Kruze page-wasm runtime: Kruze is Chromium Embedded and already executes page wasm via V8 (Liftoff + TurboFan). kwasm is the embeddable server/host-side runtime, the Koder substitute for the external runtimes those host scenarios would otherwise pull in.
Why it exists (not speculative)
Three Stack components already declare a wasm-execution seam left as a placeholder awaiting a runtime — clearing reuse-first's ≥3-consumer bar and making kwasm the best-case self-hosted flip (provide it before any consumer adopts an external, so the external is never taken on). Origin: stack#155.
Primary couplings
| Consumer | Relationship |
|---|---|
infra/net/jet |
internal/middleware/wasm.go — request/response wasm plugins (placeholder → kwasm in slice 5) |
products/dev/kdev |
crates/kode-plugins — editor/IDE plugin sandbox (Rust; embedding the Go kwasm = cross-language owner-decision, kwasm#016 gated) |
services/ai/sandbox |
not a kwasm consumer — its WASM tier dispatches via kbox run (kbox capability:wasm_workload), SANDBOX-024/sandbox-RFC-002, not an embedded engine |
engines/lang/koda |
Koda already targets wasm; long-term authoring-language candidate (slice 6) |
policies/self-hosted-first.kmd |
flip policy governing the gates |
Implementation status
| Slice | Scope | Status |
|---|---|---|
| 1 | Binary-format decoder (preamble + all sections; bodies/const-exprs raw) | ✅ done — engine/, decodes real kvg.wasm end-to-end |
| 2 | Instruction decoder (MVP + reference-types + 0xFC bulk-memory) | ✅ done — engine/instr.go+expr.go, decodes 1.6M instrs of real kvg.wasm |
| 2b (#007) | Module & control-flow validation (index bounds, limits, const-exprs) | ✅ done — engine/validate.go, real kvg.wasm validates clean |
| 2b-ii (#009) | Operand type-checking (value-stack) | ✅ done — engine/typecheck.go, full Validate type-checks 1.6M instrs of real kvg.wasm |
| 2c (#008) | SIMD (0xFD) instruction decoding | ✅ done — Opcode→uint32, all immediate shapes; full instr-set coverage |
| 3 | Interpreter core — numeric + control execution (+ call-depth sandbox) | ✅ done — engine/runtime.go+interp.go; runs recursionloopsbr_table/traps |
| 3·2 (#010) | Interpreter linear memory (loadstoregrow + data segments + bulk ops) | ✅ done — engine/mem.go; OOB-trapped, fillcopyinit |
| 3·3 (#011) | Interpreter tables + call_indirect + element segments |
✅ done — engine/table.go; nullOOBtype-mismatch traps |
| 3·4 (#012) | Interpreter host-function imports (imports-first index spaces) | ✅ done — real kvg.wasm fully instantiates (22 imports) |
| 5·1 (#013) | Go embedding API surface (Compile, Memory accessors, Caller, fuel/ctx) | ✅ done — engine/api.go; host reads guest memory |
| 4·1 (#014) | WASI preview-1 command subset (stdioargsclockrandomproc_exit) | ✅ done — engine/wasi.go; hello-world runs |
| 4·2a (#015) | WASI capability-scoped FS — read path (preopen, pathopen, fdread) | ✅ done — engine/wasi_fs.go; deny-by-default escape |
| 4·2b (#004) | WASI FS writecreate path (O_CREATTRUNC, file fd_write) | ✅ done — engine/wasi_fs.go; create→write→seek→read |
| 5·2 (#005) | First consumer: Jet wasm middleware on kwasm | ✅ done — infra/net/jet/internal/middleware/wasm.go flipped off the wazero placeholder; koder.* host ABI (headerpathbody), per-request fuel+timeout, 3 e2e tests green; self-hosted g4_capability met |
| 6 | Koda authoring migration | gated (Koda maturity) |
Language: Go for v1 (two of three consumers are Go; embeddable-from-Go is the primary requirement). Koda rewrite tracked as the long-term self-hosted ideal.
Boundaries
- Slice 1 retains function bodies and constant expressions as raw bytes;
per-instruction decoding and validation are slice 2.
- Shared-memory / 64-bit-memory limit flags and SIMD const-exprs decode in later
slices as the matching execution semantics land.
- Distinct from kbox
capability:wasm_workload(self-hosted-pairs.mdrow 13),which dispatches OCI-wasm container workloads rather than embedding a runtime.