0008 - Hot reload mechanism revised after feasibility spike
Status: Accepted (supersedes 0005)
Context
ADR 0005 fixed hot reload with state preservation as the project
bet and assumed a specific mechanism: compile UI views as a cdylib, load/swap it with
libloading, and hand a serde snapshot to the new library, with a state-preserving process
restart as the documented fallback.
Slice 0 of spec 0004 ran a viability spike on 2026-11-16 (Linux
7.3.4 x86_64, Wayland/niri, 12 CPUs, 22 GiB RAM, rustc 1.99.1 stable, cargo 1.99.1, debug profile,
warm incremental builds, gpui = "=0.2.2", libloading = "0.8.9") to validate that mechanism
before committing implementation effort.
Observed evidence:
- Mechanics:
dlopen/dlsym/dlcloseof versioned C-ABIcdylibartifacts worked for symbol calls, including a 429 MB debugcdylibthat statically linked GPUI (load/unload cycles and A/B copy swaps returned;dlclosereturning is necessary but not sufficient proof of safe unload under a live GUI/session with threads, TLS, and platform resources). - Boundary feasibility (GPUI 0.2.2): mounting UI view/render code from a separately loaded
library into a host-owned GPUI application is not feasible under standard Rust/cargo builds.
Window::replace_rootis generic over the concreteRenderroot type;AnyViewstores an entity plus a monomorphizedrender::<V>path that downcasts toEntity<V>and updates the view in the hostAppentity map;AnyElementis arena-backed in a thread-local element arena; and entities/refcounts depend onTypeIdand hostAppstorage. Upstream GPUI 0.2.2 ships as an rlib only, so host and reloadable library would carry separate GPUI instances, statics, type identities, and runtime stores. Crossing Rust/GPUI types over a C-ABI boundary is unsound and incompatible with normal GPUI view construction (impl Render,div()/elements/entities). - Build cost: warm incremental rebuild of a realistic GPUI-view
cdylib(trivial string change in a view) took 2m50s cargo / ~171 s wall in the spike run (full relink of a 429 MB debugcdylib, with package-cache/build-dir lock contention noted). Toy comparisons rebuilt in 1.81 s (monolithic GPUI bin), 0.60 s (trivial GPUI-dependentcdylibexport), and 0.17 s (no-depcdylib), showing that artifact split alone is not sufficient and a realistic view library relink is prohibitive for the < 500 ms budget. - Phase 0 baseline: relaunch loop save-to-visible remains ~60 s (relink-dominated), not hot reload.
Decision
Auro retains the hot-reload goal and contract from ADR 0005, but rejects the assumed
cdylib/libloading view-swap mechanism for GPUI view/render code on the current stack.
- Retained: target < 500 ms save-to-visible for a warm view-only change with preserved opted-in
state (a target until measured per spec 0004 D6); a long-lived dev host that owns the GPUI
application/window/event loop, runtime, managed host state, and snapshot store; versioned,
opt-in
serde-compatible snapshot/restore with visible resets; failed builds keep the previous UI running; failed or unsafe reloads fall back honestly and are never labelled "hot reloaded". - Rejected: swapping a separately loaded/unloaded
cdylibthat constructs or mounts GPUI views into a host-owned GPUI application as the hot-reload mechanism, given GPUI 0.2.2 type/instance boundaries and observed rebuild cost for a realistic view artifact. - Direction: pursue a same-process reload mechanism that keeps one GPUI/App instance and reloaded UI code in the same process and type universe (function-level/in-process hotpatching is the leading candidate to prototype, subject to OS/architecture/toolchain feasibility), or another mechanism proven to satisfy the observable contract. The selected mechanism, its layout/build model, and measured performance are recorded in spec 0004 and follow-up ADRs/RFCs as they are proven.
- Until proven:
auro devremains a relaunch loop by default. State-preserving process restart is the documented fallback when a reload cannot be performed safely; it is never presented as hot reload.
Consequences
Easier
- Implementation effort is not spent on a mechanism shown infeasible for the current renderer/API.
- The observable contract (latency target, state preservation, honest diagnostics/fallback) stays stable while the mechanism is researched.
Harder
- The path to < 500 ms is less certain: in-process/function-level patching is research-heavy and platform/toolchain constrained.
- Achieving fast reload likely requires a build/layout strategy that minimises relink/patch scope for view changes, not just code splitting.
- Specs and tooling must distinguish "reloadable change", "state-preserving restart", and "hard failure" without assuming library unload/load.
Forbidden
- Presenting a process restart as hot reload.
- Claiming the < 500 ms target is met without measurement recorded per spec 0004 D6.
- A reload path that leaves tasks, callbacks, or state running against replaced/unloaded code.
- Reintroducing
cdylibswap for GPUI view code without new evidence that resolves the type/instance, mount, unload, and performance constraints recorded in spec 0004.