Skip to content
Kronik Maintainers edited this page Nov 13, 2026 · 2 revisions

M0 spikes

Milestone M0 of the build brief asked five technical questions before the runtime was designed. Each was answered by a small standalone spike, and each answer became an architecture decision record:

Spike Question ADR
A Can a Wasm component run deterministically, with a fresh instance per turn, enforced fuel/memory limits and a closed import allowlist? 0001
B Does a TypeScript component built with ComponentizeJS run in the same world, what does it import, and what does a fresh instance per turn cost? 0002
C Can runsc run an unpacked OCI bundle without KVM, and what is the best bridge from the host into the sandbox? 0003
D Should the deterministic simulation use madsim or an executor of our own? 0004
E Can a guest's SQL in a savepoint be captured as a changeset and re-applied deterministically, and how should the state be stored? 0005

The spikes were standalone projects with their own lockfiles, excluded from the Cargo workspace, and they were archived once M0 closed. M0 closed before the repository's public history, which starts with the first v0.1.0 release candidate (ac93821c, 2026-10-28); its v0.0.0 tag was never published. The original spike code is not part of the public repository; the decisions and measurements below are carried forward in the ADRs and the production crates.

Spike A: Wasmtime configuration for deterministic turns (ADR 0001, 2026-10-24)

Question. Every turn must be a deterministic function of code hash, engine version, input, recorded effect results, logical time, seed and starting state; all nondeterminism must reach the guest through host calls; and linear memory must never be state, so every turn needs a new instance. The brief asks for canonicalized NaNs, deterministic or disabled relaxed SIMD, no threads, fuel instead of epochs, a memory limiter, a precompiled code store and a closed WASI allowlist.

Approach. A host harness implementing every import of the draft actor WIT, with a Rust guest on wasm32-wasip2 that deliberately touches nondeterministic APIs (SystemTime, Instant, HashMap randomization, console output, NaNs, a static counter) plus modes that exhaust fuel, allocate, trap and call denied effects. The harness reported ordered traces of every host call, and ran 22 checks over fresh instances, pools, the code cache and two engines.

Key results.

  • The allowlist is enforceable: components importing anything outside it are rejected at deploy with IMPORT_NOT_ALLOWED, and the checks covered synthetic and std::fs components.
  • Outcomes were byte-identical across fresh instances, compiled and deserialized code, processes and seeds; clocks and Instant follow logical time, and the static counter is reset on every turn.
  • Fuel exhaustion, memory limits, traps and denied effects were classified as designed.
  • On a 110–116 KB Rust guest, a whole trivial turn took 38.1 µs on the development machine and 45.6 µs on the 2-vCPU test VPS (about 23k and 19.6k turns/s per thread with the pooling allocator); instantiating from a pool took 11.2–14.8 µs against 36.7–52.5 µs on demand. Compiling took 83 ms and 175 ms, and loading cached code 155 µs and 333 µs.
  • The same probe digest was produced on both machines, so the configuration is deterministic across CPUs.
  • The brief's 1 000 committed turns/s target leaves Wasm execution well under 10 % of the budget; logging and fsync dominate.

Decision. Wasmtime with a pinned engine version and feature set, the pooling allocator, InstancePre, precompiled code per code hash and engine version, fuel, a deterministic WASI allowlist, async host functions and fresh instances per turn (ADR 0001; the engine was later patched to the current maintained release line).

Spike B: TypeScript components with jco and ComponentizeJS (ADR 0002, 2026-10-25)

Question. M0 asked for a TypeScript component built the way kronik build would build it to run in the same actor world with its imports listed. The open question was the cost of a fresh instance per turn for JavaScript components, and what pre-initialization such components need.

Approach. A probe actor and the brief's counter written against the raw bindings, built with the pinned jco 1.39.0 / ComponentizeJS 0.23.0 / TypeScript toolchain into several variants (chosen feature flags, AOT and default builds, a QuickJS comparison and a no-WASI comparison). The components ran unmodified in spike A's harness for determinism checks, import listing and benchmarks; two experiments used a patched harness copy to call handle repeatedly on one instance and to keep pool slots resident, both of which Kronik must not do.

Key results.

  • Imports stay within the allowlist when http, fetch-event and stdio are disabled at build time; module-scope randomness fails the build instead of being baked into the snapshot.
  • Math.random() is served by the host's wasi:random and follows the turn seed; all JavaScript clock and randomness sources follow the turn's logical time.
  • A fresh instance per turn is cheap to create (~35 µs) but the first call on it carries the engine warm-up: on the test VPS a whole no-op turn took 1.3 ms and a counter turn 1.7 ms (~565 turns/s on one core), against 45.6 µs for the Rust guest. A 64 KB JSON turn took 7.1 ms.
  • Keeping pool slots resident did not help on the test VPS (the time moved to freeing the slot), and --aot did not help either; Kronik keeps Wasmtime's defaults.
  • A TypeScript component is 12.8 MB and takes 14 s to compile on the test VPS, while loading its precompiled cache takes 1.8 ms. Deploy, restore and engine upgrades therefore compile before switching code; a turn never compiles.
  • Peak memory is 9,280 KiB; the fuel cost model (~1 million fuel per turn plus about 4.3 million per 6 KB of JSON) sets the default 50 million fuel and 64 MiB limits for JavaScript kinds.

Decision. TypeScript actors are built with jco and ComponentizeJS without http, fetch-event and stdio, through the SDK's kronik build pipeline; the build records its input hash and keeps the previous component when the inputs are unchanged (ADR 0002).

Spike C: gVisor without KVM, and the sandbox bridge (ADR 0003, 2026-10-25)

Question. Foreign actors are Linux programs from OCI images in gVisor, reached from Kronik through recorded http.fetch calls. The spike asked whether runsc with the systrap platform can run an unpacked OCI bundle on a VPS without /dev/kvm, and which host-to-sandbox bridge to choose.

Approach. An OCI tool that verifies index, manifest, config and layer digests, applies layers with whiteouts and opaque directories, resolves paths inside the rootfs and generates config.json; a static echo server as the foreign actor; a network prober, a bridge benchmark and a Unix-socket shim; and experiments for cold start, limits, supervision, checkpoints, egress and alternatives.

Key results. Test VPS: Debian 13, kernel 6.12, 2 vCPU Intel Skylake under KVM without nested virtualization, 3.7 GiB RAM, cgroup v2, no /dev/kvm; gVisor release-20261019.0.

  • --platform=kvm fails without /dev/kvm; systrap starts a sandbox in about 100 ms, and the first request through a bridge is answered about 123 ms after the start. Teardown takes 17 ms.
  • The chosen bridge, one runsc port-forward --stream per connection, kept alive: p50 0.36 ms / p99 1.2 ms; new connection: 13 / 26 ms. The next best options were local port-forward (0.57 / 1.7 ms kept alive, 4.9 / 19 ms per new connection) and a Unix-socket shim (0.57 / 3.0 ms, 6.5 / 51 ms), which also broke runsc checkpoint by holding a bound host socket.
  • Egress is blocked: external TCP and UDP, DNS and the host's own public, Docker and private management addresses all fail with Network unreachable, and the sandbox has only lo.
  • CPU and memory limits work (1.00 CPU under the quota, OOM kill at the memory limit); idle cost is 3 ms of CPU per 5 s and 18 MiB in the cgroup.
  • Multi-layer images with real whiteouts unpack correctly, and a tampered layer blob is rejected.

Decision. Foreign actors run on runsc systrap with a network namespace containing only lo; every connection is one runsc port-forward --stream helper; calls are recorded as effects (ADR 0003).

Spike D: Deterministic simulation testing (ADR 0004, 2026-10-25)

Question. The brief requires kronik-sim to run the whole daemon in a simulated world: virtual clock, disk that loses unsynced writes and tears the last one, simulated external services with latency and faults, random crashes and restarts, all on a single-threaded deterministic executor. The question was whether to use madsim or write our own executor.

Approach. A mini daemon containing the hard parts — segmented log with CRC, group commit and fdatasync, fresh Wasmtime instances per turn, one external effect per turn, real SQLite state, LSN-ordered apply and recovery — run on both executors, plus 1-million-step runs, 10 000-seed volume runs and a mutation suite that seeds 100 known bugs.

Key results.

  • The own executor was chosen: it needed control over fsync, torn writes and crash points that a general-purpose simulator does not expose. It ran 2.6–2.9 million polls/s on the development machine and 1.44 million on the test VPS (madsim measured 5.0 million on the development machine); DST volume was 30.2 seeds/s against madsim's 29.9, and 18.4 seeds/s on the test VPS. 1 000 seeds ran in 28.1 s with 8 threads, 200 in 6.8 s with 2.
  • A 1 199 684-poll run with 911 crashes, 138 fsync-error restarts, 106 torn tails and 26 valid records after a tear finished with 0 violations; a real tokio run reached 297 turns/s on the development machine and 314 on the test VPS with identical recovered state and empty identity replay.
  • Every seeded bug was caught by some seed: effect before the durable turn begin (100/100 seeds), acknowledgement before fsync (100/100), missing torn-tail truncation (36/100), and others.
  • The spike produced the findings that shaped M1: recovery rules for active versus closed segments, the applier being fed by the log writer, the logical-time high-water mark over all records, idempotency bookkeeping, the cost of an effect (three durable appends) and the need for O(tail) crash recovery.

Decision. kronik-sim implements its own single-threaded executor behind the Clock, Fs, Net, Spawner, EntropySource and ProcessRunner traits (ADR 0004).

Spike E: Per-actor SQL state (ADR 0005, 2026-10-25)

Question. Can a turn's SQL run in a savepoint, be captured as a changeset, rolled back and re-applied so production, recovery and replay build the same database deterministically; can DDL, tables without a primary key, time and randomness, per-subject splits and storage layout all be handled?

Approach. A prototype actor database around bundled SQLite, using the SQLite session extension through one allowlisted FFI module, with 30 checks and a benchmark on real disk.

Key results. All 30 checks passed on both the development machine and the test VPS.

  • The savepoint/changeset/rollback approach costs about 10x direct SQL execution — about 200 µs per turn — but stays inside the build brief's targets. DDL is recorded separately and allowed only in migrate, before the first DML; tables without a primary key can be tracked through rowid; random() and datetime('now') follow the turn's seed and logical time.
  • One SQLite file per actor with WAL and exclusive locking measured at 24 KiB per actor (68 KiB with the WAL): 10 000 actors take 668 MiB and 20 000 files. The prototype kept 1 052 turns/s on the development machine and 392 on the test VPS for 10 000 actors with a 256-connection cache, against 3 346 and 1 991 turns/s for 256 hot actors.
  • Opening and configuring an existing actor took 386–442 µs, creating a new actor database 4.8–7.0 ms, and direct execution of a turn 19–24 µs.
  • A shared store with renamed tables was rejected as fragile; a page-store VFS was deferred.

Decision. kronik-store gets a sql module modelled on the prototype, one SQLite file per actor under the branch's data directory, an erasure operation for SQL, and per-actor applied_lsn so recovery can skip applied work (ADR 0005).