Repository navigation
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.
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 andstd::fscomponents. - Outcomes were byte-identical across fresh instances, compiled and
deserialized code, processes and seeds; clocks and
Instantfollow 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).
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-eventandstdioare disabled at build time; module-scope randomness fails the build instead of being baked into the snapshot. -
Math.random()is served by the host'swasi:randomand 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
--aotdid 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).
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=kvmfails 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 --streamper 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 brokerunsc checkpointby 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 onlylo. - 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).
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).
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()anddatetime('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).