Duolith docs

0076. Rung 1 ships source until the spike's timing opens the bytecode gate; rung 2 stays closed

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP13 (execution ladder), WP9 (native spike), D22

Context

The roadmap puts "rung 1 bytecode" in WP13 and "rung 2 behind the spike's timing result". The spike (WP9) times one function as engine bytecode, compiled TypeScript and Rust on a mid-range Android phone and an iPhone; its results go in spike/RESULTS.md. That file does not exist yet: the measurements need devices, and this repository's machines have none, nor Xcode or the Android NDK. Precompiling scripts to Lynx's bytecode also needs Lynx's toolchain, which only native builds bring in.

Decision

  • The rungs, as the build uses them: 0, tables (decision 0075); 1, a script that runs when the screen opens; 2, functions compiled ahead of time to machine code; 3, code written in Rust, in a module (decision 0078). A file's own rung is 0 or 1; rungs 2 and 3 hold code a file calls.
  • Every file not on rung 0 is on rung 1. That classification is complete and is what the build report shows.
  • **How rung 1 ships is decided per target in crates/runtime/src/ladder.rs:** on the web always as source (the browser compiles it); on iOS and Android as bytecode once the bytecode gate opens, and as source until then. Source is the fallback path, and it is what native output uses today.
  • The bytecode gate is closed, waiting for spike/RESULTS.md to show bytecode faster to start than source on both phones. Opening it is changing bytecode_gate() to Gate::Open and having the native emitter call Lynx's bytecode compiler; the report then shows "script": "bytecode" for rung 1 files on native targets.
  • Rung 2 stays closed (compiled_functions_gate()), for the same timing result, and automatic promotion to it is post-v1 (docs/plan/post-v1.md).
  • The build report carries the gate's state (bytecode.isOpen, bytecode.waitingFor), so nobody mistakes source for bytecode.

Alternatives considered

OptionWhy not
Ship bytecode on native nowUnmeasured: bytecode can be larger, and the spike exists to learn whether it starts faster on the target phones
Treat the web's JavaScript as "bytecode"It is not; the report would mislead
Leave rung 1 unclassified until the spikeThe report and the native emitter need a rung for every file now

Consequences

  • The gate is one function; opening it needs the spike's numbers and Mik's approval.
  • native/DEVICE-CHECKLIST.md lists the device steps.