fiber

6. The extension runtime is embedded Lua 5.4

Date: 2026-09-21

Status

Accepted. Settled by Extension runtime: Lua or something else? and, for what a package holds and how it is shared, Extension distribution, and, for what runs in the terminal, TUI extension seams, against the runtime comparison in #3. The contract is docs/extensions.md; the trust model is docs/permissions.md; the seams are docs/architecture.md. Measurements: research/extension-runtime/ (pass1 disqualification probes, pass2 RSS sweep, pass3 authoring probe, vm-isolation).

Context

Map premise 8: v0.0.1 ships an extension system where an extension registers through the same three seams a built-in does — tool, provider and hook — and can replace a built-in by name. The runtime has to serve an ecosystem where people freely build and share extensions, as pi's does, with no sandbox.

Four constraints were fixed going in: a hook must answer synchronously inside a turn under an enforced timeout (docs/architecture.md); an extension runs with the account's full rights and the runtime is not a security boundary (docs/permissions.md); no async runtime, no tokio, zero idle CPU (ADR 0004); and runtime memory, not binary size, is the metric that matters.

Candidates measured: Lua 5.4 and Luau (both via mlua), JavaScript via rquickjs (QuickJS), and — considered and rejected without a full sweep — Starlark, WASM (wasmtime/wasmi), and full TypeScript on a V8-class runtime.

Decision

Embed Lua 5.4 through mlua (vendored). One Lua VM per extension, created lazily on first use. No sandbox. How providers use it is ADR 0007.

The evidence, in the order it decided things:

One VM per extension costs ~120 KiB per extension and gives per-extension memory caps, separate GC and crash containment; a shared VM with per-_ENV isolation is leaner at large counts and is the documented fallback (research/extension-runtime/vm-isolation). Lazy instantiation means a session with no extension in use creates no VM and pays no idle cost.

Consequences

Rejected

QuickJS (JavaScript via rquickjs). The strongest alternative: uncatchable deadline from one call, JSON.parse native, best training-data familiarity, and prebuilt bindings for all three targets. Rejected on memory — ~2× Lua per instance and it never returns memory to the OS — after pass3 showed its familiarity advantage did not convert into an authoring edge. It was the "JS syntax without the ecosystem" middle option, and captured neither the low-RSS prize nor the npm prize.

Luau. Uncatchable deadline with no staging, a first-class sandbox(), native gradual types, and a working require. Rejected on memory: heaviest of the candidates on both a fixed per-process baseline (4–6 MiB before any work) and per-instance cost, and the penalty is the VM itself — measured identical with the sandbox on and off — so dropping the sandbox we do not want buys nothing.

Starlark. Ruled out in #3: idle RSS in the 6.5 MiB band and peak RSS that scaled to 45 MiB on a loop-heavy script.

WASM (wasmtime/wasmi). Its one real edge is a capability sandbox the owner explicitly does not want. wasmtime is the heaviest runtime and needs tokio for any real I/O (via wasmtime-wasi), violating ADR 0004; wasmi is lean but shares the disqualifier: wasm is bytecode, so a model-authored, git-distributed extension cannot run as source without a compile step.

Full TypeScript on a V8-class runtime (the pi model). Buys npm, real types, and near-drop-in portability of pi's extension ecosystem. Rejected because it is a different architecture, not a runtime knob: embedding V8 costs tens of MiB of RSS and a JIT, breaking the low-RSS premise; shelling out to system Node/Bun breaks single-binary distribution. npm's libraries stay reachable through a process extension, which runs Node or Bun as a separate program only when a person installs one.

TypeScript for the terminal's half. UI is where TypeScript's reach is strongest, and pi's UI extensions are TypeScript. Two forms were weighed for #163. TUI extensions on Bun or Node would be a process beside the terminal, about 20 MiB for Bun idle, and each render would cross a pipe at 56 to 79 µs against 8 µs into Lua. npm's terminal libraries, such as Ink and OpenTUI, each own the whole screen, so none can draw into a slot. Rewriting the terminal itself in TypeScript would let extensions use its own components, as pi's do, but reopens #147: OpenTUI on Bun measured 88 MiB idle with idle wakeups, against ratatui's 1.9 MiB and none (research/tui-surface/). The terminal is a client, so it can be rewritten later without touching a session.