No stringly bridge
Commands, events and arguments are Rust types. The schema is generated from the same signature the compiler checks.
Auro 0.1.0-alpha.7 · native desktop
Auro keeps Tauri's app model - configuration, windows, capabilities, bundling, signed updates - and replaces the webview with GPUI, Zed's GPU-accelerated Rust UI toolkit. One Rust codebase, from window to command.
Pre-alpha. The CLI alpha is public; the framework is not production-ready. Hot reload is measured only for the documented data boundary. Platform status.
auro new writes a four-crate workspace: the bin, the view, the
hot boundary and the shared data types.
auro dev builds, launches and watches. The default loop rebuilds
and restarts; the hot path is opt-in and has a narrower contract.
auro build makes a release binary. auro bundle uses
the platform packaging paths; support is documented, not assumed.
The schema is derived from the Rust signature, and the call site is a Rust call. A renamed command or a wrong argument is a compile error, not a runtime string lookup.
Cheap mutation stays on the UI thread. File I/O and network calls run as
commands on tokio; the result returns to the main thread, updates
an entity, and the next frame renders it.
There is no invoke("name", {...}) in first-party code because
there is no JavaScript bridge to invoke through.
Read the threading contract.
#[auro::command]
async fn save_document(
path: PathBuf,
body: String,
) -> Result<Saved, AuroError> {
tokio::fs::write(&path, body).await?;
Ok(Saved { path, bytes: body.len() })
}
// The call site is typed too.
let saved = api::save_document(doc.path, doc.body).await?;
Commands, events and arguments are Rust types. The schema is generated from the same signature the compiler checks.
The app draws through GPUI on the GPU. The webview is a scoped Phase 4 escape hatch for OAuth and embedded docs, not the foundation.
Grants are deny-by-default and scoped to filesystem, network, shell, clipboard, notifications and keychain. Most UI code needs no runtime check.
Config, window management, lifecycle, single-instance, tray, shortcuts and deep links stay in the framework, where Tauri already proved the shape.
Update manifests are signed, artifacts are hashed and staged, and apply paths are platform-specific. The updater is a feature, not a default.
Edits in the documented data boundary measured 368 ms median on Linux. View, layout, type and dependency edits rebuild the host and restart the process.
auro-ui.
The CLI is published; the framework contract is not stable. Read the limits before choosing it for anything that matters.
0.1.0-alpha.7 is on crates.io; there is no stable release.This gets a shell to a native Auro window with the published alpha CLI, then explains what the default dev loop actually does. Auro is pre-alpha: use this to evaluate the shape of the framework, not to ship a product.
You need:
cargo on PATH. The scaffold uses edition 2024 and declares rust-version = "1.90".0.1.0-alpha.7.The CLI is a cargo-installed binary named auro; the crate is auro-cli.
cargo install auro-cli --version 0.1.0-alpha.7
auro --version
If the second command does not run, check that ~/.cargo/bin is on PATH. To build the CLI from
a checkout instead, follow CONTRIBUTING.
auro new hello
cd hello
auro new refuses a non-empty directory. It writes a four-crate workspace plus configuration:
| Path | Role |
|---|---|
Auro.toml | App identifier, windows, dev watch list, hot-mode switch and bundle icon. |
src/main.rs | Thin binary: calls the UI crate with the hot boundary function. |
ui/ | Render, window, element tree and command functions. It does not depend on data. |
data/ | The hot boundary: view_data() -> HotData, deliberately tiny and framework-free. |
types/ | Shared ViewData and the fixed HotData frame; no framework dependency. |
The split is the hot-reload boundary: changing data/src rebuilds a small crate and relinks the
binary, while ui and GPUI stay compiled. That is why the boundary is separate, and why a change
outside it is not a view reload.
auro dev
The command builds the app, launches it as a native window, and watches the paths in [dev] watch.
A save rebuilds, relaunches and restores opted-in state from a snapshot when the snapshot version is
compatible. The previous app stays visible while a replacement builds.
This default loop is not hot reload. It is a build-and-restart loop, and the output says
restarted (state restored) or restarted (state reset) rather than pretending otherwise.
To check the toolchain, GPUI pin, config parse, hot-mode availability and Linux libraries:
auro doctor
On Linux, auro doctor reports each native library as ok or MISSING. Missing libraries are a
build problem, not an Auro bug.
Hot mode is opt-in. Set it in Auro.toml:
[dev]
hot = true
It also needs dioxus-cli 0.7.x on PATH (tested with 0.7.10) or an explicit AURO_DX path.
auro doctor reports whether the app declares the hot-reload feature and whether the devserver is
available.
With hot mode on:
data/src is a boundary edit. The patch replaces that function; the running host keeps
its window and state.ui, types, the binary, a dependency, a manifest or the profile is host code. It
rebuilds and restarts the devserver and app, restoring the snapshot when compatible.The full contract, including failure behavior and what is not reloadable, is in hot reload and spec 0004.
auro build
auro bundle
auro build produces the release binary. auro bundle asks the platform bundler for the host's
installers. Packaging support is uneven by platform and is documented in
platform support; do not assume every target produces every
installer.
Useful variants:
auro dev --dir /path/to/app
auro dev --dir . --config app.product-name="Demo"
auro build --dir .
auro bundle --dir .
| If you want to | Read |
|---|---|
| Understand the app loop | Architecture overview |
| Follow a command across threads | Threading and IPC |
| Change configuration | Configuration |
| Know what is actually verified | Platform support |
| Know why a decision was made | Decision records |
| Check the alpha gates | Alpha release |
For a bug or a build failure, include the output of auro doctor, the host OS and compositor, the
CLI version, and the commit or crate version. The project is pre-alpha; a reproducible report is
more useful than a compatibility claim.
Auro is an application shell around a renderer it does not own. Every architectural rule below follows from that split.
+-----------------------------------------------------------+
| auro-cli new . dev . build . bundle . add . doctor |
+-----------------------------------------------------------+
| auro-core |
| App . WindowManager . Config . Lifecycle . |
| Command registry . State store . Event bus . Instance |
+--------------+-------------------+------------------------+
| auro-ui | auro-ipc | auro-perms |
| GPUI + kit | typed bus | capabilities |
+--------------+-------------------+------------------------+
| auro-plugins in-process (cdylib) | out-of-process RPC |
+-----------------------------------------------------------+
| auro-bundle . auro-update . auro-sign |
+-----------------------------------------------------------+
The diagram is a layering, not a dependency graph: a layer may use the layer below it, and
auro-core is the only crate that composes the others. The Phase 0 workspace fixes the current
Cargo.toml edges for the materialized crates; the full crate graph remains the intended
direction as later phases land.
| Layer | Owns | Must not |
|---|---|---|
auro-cli | project scaffolding, dev loop, bundling entry points, diagnostics | contain runtime logic the app needs |
auro-core | App, window manager, config, lifecycle, command registry, state store, event bus, single-instance guard and forwarding | render anything |
auro-ui | GPUI re-export, toolkit seam, tokens, minimal primitives | ship a component toolkit; check permissions |
auro-ipc | typed command transport, schema derivation, event delivery | decide policy |
auro-perms | capability manifests, runtime enforcement for plugin and content boundaries | guard code that the compiler already guards |
auro-plugins | plugin manifests, in-process cdylib hosts, out-of-process RPC | assume plugin code is trusted |
auro-services | platform services: autostart, notifications, keychain, global shortcuts, tray, deep links (specs 0017-0022) | perform OS work the app did not ask for |
auro-bundle, auro-update, auro-sign | packaging per platform, signed manifests, staged downloads, platform apply/rollback and notarization tooling, key handling | run inside the app's main loop |
async fn on the tokio runtime. File I/O,
network, parsing - anything that can block - happens here.Result<T, AuroError>. There is no serialization
boundary unless the command crosses the plugin boundary.Entity and calling
cx.notify(), which schedules a render.// Current workspace API (unpublished).
#[auro::command]
async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> {
tokio::fs::write(&path, body).await?;
Ok(Saved { path, bytes: body.len() })
}
The call site is a Rust call, so a wrong argument type is a compile error rather than an
invoke failure at runtime.
serde snapshot so a hot reload or a
state-preserving restart can restore opted-in state. Opt-in hot mode patches a small boundary
crate in-process; the contract is in spec 0004, the mechanism in
ADR 0008 and the boundary layout in
ADR 0022.The boundary rule that keeps this honest: nothing outside auro-core holds a global mutable
reference to app state, and nothing on the main thread blocks on I/O.
Tracked in ROADMAP §8:
Resolved: component kit — Auro ships no toolkit; the application chooses one (ADR 0009, choosing a toolkit).
Anything in this book that depends on those answers is marked as open where it appears.
The Phase 0 workspace is in the tree. This chapter is the contract it satisfies and the map for what comes next; it is deliberately more specific than the README.
Eleven crates are materialized now; the rest arrive with the phase that needs them.
| Crate | Kind | Responsibility | Status |
|---|---|---|---|
auro | library | facade re-exporting the supported API surface; services and tray are opt-in features | Phase 0-2, in tree |
auro-cli | binary | new, dev, build, bundle, generate-key, manifest, delta, notarize, bench, doctor | Phase 0-2, in tree |
auro-core | library | config schema, state store, lifecycle events, single-instance guard and forwarding; window manager and event delivery live in the facade | Phase 1, in tree (config, state, lifecycle, instance) |
auro-ui | library | GPUI re-export, tokens, minimal primitives (Button with keyboard activation); no component toolkit (ADR 0009) | Phase 0-2, in tree (re-exports, Button, tokens) |
auro-ipc | library | typed transport, command schemas, runtime bridge | Phase 1, in tree |
auro-macros | proc-macro | #[command], generate_handler! | Phase 0, in tree |
auro-perms | library | capability manifests and runtime enforcement (spec 0016) | Phase 2, in tree |
auro-plugins | library | plugin manifest and host (in-process and out-of-process) | planned, Phase 3 |
auro-services | library | platform services: autostart, notifications, keychain, global shortcuts, tray, deep links (specs 0017-0022) | Phase 2, in tree |
auro-bundle | library | platform packaging via tauri-bundler (spec 0010) | Phase 2, in tree |
auro-sign | library | Ed25519 keys, signatures, SHA-256 (spec 0011) | Phase 2, in tree |
auro-update | library | signed manifests, stage/delta/rollout runtime, platform apply and journal-driven restart/rollback (specs 0012-0014, 0025-0032) | Phase 2, in tree |
Cargo.toml problem.auro-core composes; it is not a dumping ground. Anything that only one platform or one
subcommand needs belongs in that crate.auro-ui has no policy. No permission checks, no filesystem access, no config reads.
A primitive that needs data takes it as an argument.auro-perms has no I/O. It answers "is this capability granted for this subject?" and
returns a verdict. Enforcement points live at the call sites that perform the effect.auro-ui re-exports only the GPUI surface Auro's
primitives use, so upstream churn is absorbed in one place.gpui-component and similar crates are application
dependencies, initialized through App::setup and wrapped with App::root_with
(ADR 0009).auro-ui imports gpui directly. That includes examples unless they are
explicitly demonstrating the escape hatch.auro-* in the manifest, auro_* in code, auro as the user-facing facade.auro::prelude only when it is stable enough to promise.auro is a separate facade crate or auro-core re-exported under a shorter name.auro-update and auro-sign are two crates or one crate with features. They are named
separately in the roadmap, and their consumers are narrow (auro-cli and auro-update), so this
can be settled when the updater API stabilizes.Two rules generate every other rule in this chapter:
| Work | Thread | Mechanism |
|---|---|---|
| Rendering, layout, input, focus | main | Application::run |
| Entity mutation | main | cx.update, cx.listener, AsyncApp::update |
| Spawning async work | main -> runtime | cx.spawn |
| File, network, process, parsing | tokio worker threads | async fn in a command |
| Plugin RPC | worker threads | out-of-process transport |
Rules:
std::fs, no reqwest::blocking, no Command::output,
no synchronous sleep in a render or event handler.cx.notify().await while holding a UI borrow. Clone what you need, drop the borrow, then spawn.A command is a Rust function with a typed signature. The macro derives the argument schema, the result schema, and the registry entry; it does not introduce a wire format the compiler cannot see.
// Current workspace API (unpublished).
#[auro::command]
async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> {
tokio::fs::write(&path, body).await?;
Ok(Saved { path, bytes: body.len() })
}
Constraints the macro is expected to enforce:
serde::Serialize / Deserialize plus schemars::JsonSchema,
because the plugin boundary still needs a schema;AuroError type, with From conversions for std::io::Error and
serde_json::Error so ? works in command bodies;Tauri's default call is invoke("save_document", { path, body }): the name is a string, the
payload is JSON, and a typo is a runtime error in the browser console. Auro has no browser and no
JS, so the call site is:
let saved = api::save_document(doc.path, doc.body).await?;
A wrong argument count, a wrong type, or a renamed command is a compile error. The schema still exists, but for classification and plugin transport, not for runtime argument checking.
Events flow main-ward: a background task finishes and updates the entity that cares, rather than broadcasting an untyped payload that every view filters. This avoids the usual event-bus failure mode where a renamed event silently stops working.
Local parent/child wiring can use GPUI entity events. For app-wide notifications Auro provides one typed path (spec 0007):
EventSender is cloneable and Send + Sync; commands receive it as State<EventSender> (or an
app captures App::event_sender()), and emit queues the event.App::on_event::<E> handlers
with &E and &mut App.emit(event, cx) dispatches synchronously.Ready, WindowOpened, WindowClosed, Exiting) are a separate closed enum;
they are not mixed into the user event queue.There are no string topics and no untyped broadcast payloads. Events with no subscriber are dropped; backpressure is not implemented yet.
Result<T, AuroError>; no unwrap outside tests, and no unwrap in a
command.AuroError is #[non_exhaustive] from the start: adding a variant must not be a breaking
change for downstream matches.Auro does not copy Tauri's capability model, because most of what Tauri checks at runtime does not
exist here. When the frontend is your own Rust code, a call to std::fs::write is not a privilege
escalation - it is your code, compiled in.
What remains is a real security boundary:
| Boundary | Why it is untrusted | Enforced at |
|---|---|---|
| Plugins | third-party code, may be installed after the app ships | plugin host, per call |
| Content | documents opened, scripts evaluated, remote data | the API that consumes it |
| Webview escape hatch | a browser pointed at content we do not control | the hatch itself, phase 4 |
fs, net, shell,
clipboard, notification, keychain. Anything unlisted is refused at the call site.auro-perms returns a
verdict; the code that opens the
file or spawns the process is the code that asks. A single choke point far from the effect is
how permission models rot.cdylib shares the address space, so a bug there
can corrupt the host. The default is out-of-process; in-process is opt-in and documented as a
trade, not as a security boundary.A denial is a typed error returned to the caller, not a panic and not a silently ignored call:
// Implemented shape (spec 0016); the plugin host wiring is still pending.
policy.check_scope("plugin:notes", auro::perms::Capability::Fs, "/var/lib/notes/a.txt")?;
The error names the scope, the subject and the pattern that failed to match, so a plugin author can fix the manifest without reading framework source.
Auro.toml section, or a separate capabilities.json next to the plugin.Status: the pieces below exist in tree and are unit-tested, but no update has been served, signed with a release key, installed on a packaged app and verified end to end on all three platforms. Apple credentials and a macOS runtime are unavailable here.
The contract lives in the specs: 0012 (manifest), 0013 (check/stage), 0014, 0025, 0026, 0027, 0029, 0030, 0031 and 0032.
One Ed25519 key pair per app. The app pins the public key; the release operator signs a JSON manifest whose signature covers version, platform, URL, size, SHA-256, notes, publication time and the optional delta/rollout fields. The manifest signature is the trust boundary, not TLS and not the package manager. A signed older manifest can be replayed, so the normal updater refuses a downgrade; an explicit rollback path exists for a caller that chooses an older release.
Updater checks the manifest before any network request, downloads with timeouts and an exact
size bound, verifies SHA-256, and publishes the artifact atomically under its content-addressed
name in a staging directory. A staged file that still verifies is reused. stage_from_path is the
same path for an artifact already on disk. Deltas are base-bound and produce a full artifact that
is verified again; a staged rollout is a deterministic percentage keyed by a stable per-install
value. Full download is always the fallback.
| Artifact | Path | Backup/rollback |
|---|---|---|
| AppImage | Atomic replacement, mode 0755 | Hard-link/copy backup, explicit receipt |
.deb | dpkg -i through pkexec | Package manager transaction; opt-in older-package rollback |
.rpm | rpm -U through pkexec | Package manager transaction; opt-in older-package rollback |
| MSI/NSIS | Silent installer, 3010 means reboot | Installer policy |
macOS .app zip | Extract, swap one bundle | Retained bundle backup, explicit receipt |
macOS .pkg | /usr/sbin/installer, AppleScript authorization | Installer policy |
The restart helper runs the apply, not the app. Elevation is explicit and helper-side: pkexec
for Linux package managers, the standard AppleScript administrator prompt for .pkg. The app
process never becomes root. pkexec codes 126/127 are authorization/execution failures; a package
manager's own non-zero code is an installer failure.
The app writes an atomically replaced JSON journal (Prepared), keeps a lock file and spawns the
same executable with AURO_UPDATE_RESTART_HELPER. The helper waits for the old process to release
the lock, re-verifies the manifest and artifact, applies the platform action, marks Applied (or
RebootRequired), and relaunches. Failures are Failed with a diagnostic and no relaunch.
The app classifies the next start with reconcile and cleans up with finalize after Complete.
The journal is user-writable local state, but its path is a trust boundary: it names the
verification key, staged artifact, target and relaunch command, so a journal planted by another
local user would choose what the helper runs. ApplyJournal::load, save and the helper lock open
refuse a journal or lock in a directory another user can write: Unix checks owner, mode, symlinks
and ancestors; Windows rejects reparse points and checks the owner/DACL; the Windows tests pass on
GitHub Actions. See spec 0033. The helper still
re-verifies the signed manifest and artifact; path trust does not replace signature verification.
.app installers return a receipt; the old artifact stays beside the target
until the app discards it..deb/.rpm. Updater::stage_rollback_from_path or
download_rollback verifies and stages one; LinuxPackageInstaller::rollback runs the explicit
downgrade flags. An ApplyPlan may carry that older package, in which case the helper retries it
once after an InstallerFailed, marks RolledBack and relaunches. A declined authorization, a
tampered artifact or a non-package apply never triggers that retry
(ADR 0021).Signing inputs are mapped to the platform bundler. Notarization is separate release hardening:
auro notarize submits a .dmg/.pkg/.app with an existing keychain profile, staples and
validates the ticket, and --verify runs the matching Gatekeeper assessment. It does not replace
the Auro manifest signature. See macOS notarization.
.pkg apply on a macOS host;Auro is the application layer. It owns configuration, windows, typed commands, state, lifecycle and the dev loop; it does not ship a component kit. That is deliberate (ADR 0009): GPUI is the renderer, widgets are the renderer's or the ecosystem's, and the app chooses what it wants to pay for.
Two builder calls make any GPUI toolkit usable:
App::setup runs after GPUI starts and before any window opens. Initialize the toolkit and
apply the theme from Auro.toml there.App::root_with builds the window root yourself, so a toolkit can own dialogs, notifications,
sheets and input focus around your view. App::root::<V> remains the shortcut for a
Default-constructed view with no wrapper.use auro::prelude::*;
use gpui_component::{Root, Theme as KitTheme, ThemeMode};
fn main() {
App::new()
.setup(|cx, config| {
gpui_component::init(cx);
let mode = match config.app.windows[0].theme {
auro::Theme::Dark => ThemeMode::Dark,
auro::Theme::Light => ThemeMode::Light,
auro::Theme::System => ThemeMode::Light, // or follow the system appearance
};
KitTheme::change(mode, None, cx);
})
.root_with::<Root>("main", |window, cx| {
let view = cx.new(|_| LogViewer::default());
cx.new(|cx| Root::new(view, window, cx))
})
.run();
}
# the app's Cargo.toml, not Auro's
[dependencies]
auro = { path = "../auro/crates/auro" }
gpui-component = "=0.5.1"
App::setup receives the parsed Config, so the theme decision uses the same file that declares
the windows. app.windows[].theme is passed through; the toolkit decides what it can honor. A
toolkit with one global theme can honor one theme per app, not a different theme per window.
auro doctor reports a non-system theme as toolkit-owned.
gpui-component tracks GPUI; Auro pins GPUI exactly. The compatibility line matters:
| Toolkit | GPUI line | Notes |
|---|---|---|
gpui-component 0.5.1 | gpui ^0.2.2 | Last line compatible with Auro's pinned renderer (2026-02-05). The probe measured 0.5.0; 0.5.1 is the newest release on the same dependency line. |
gpui-component 0.6+ | gpui-pre ^0.3.x | Requires moving Auro's GPUI pin and revalidating hot reload. Current 0.10.0 pins gpui-pre =0.3.12. |
| none | gpui 0.2.2 | div(), GPUI elements and Auro's minimal Button; smallest app. |
Measured probe (2026-11-17, Linux x86_64, release, stripped, panic = "abort", one Button plus
the toolkit Root): 22.0 MB with gpui-component 0.5.0 against 15.5 MB for the minimal
Auro app; spawn→window 147.3 ms against 139.8 ms (median, N=5; not first paint). The app pays the
toolkit's size; the framework's minimal app does not.
These numbers are context, not a benchmark contract. Re-measure when the toolkit or GPUI line changes, and record the environment with the result.
The working integration is in examples/log-viewer: two
windows, a background event stream, and settings, all with the toolkit at the app level.
auro-ui or auro-core.Button as a component kit.If a toolkit later reaches a stable 1.0 that can be pinned without moving GPUI, an optional integration crate can wrap it. The core still ships no toolkit.
This is the existential bet of the project. If the edit loop stays at a multi-second/minute rebuild-and-relaunch, nobody leaves the web, and the rest of Auro does not matter.
Target: edit to see in under 500 ms, with app state preserved.
The target and observable contract are fixed; the mechanism is under revision with prototype evidence. Normative dev-loop contract, staging, and acceptance are drafted in spec 0004.
auro dev rebuilds and relaunches the app process (Phase 0). A saved change to
a visible relaunch measured ~60 s on the development machine (relink dominates, 2026-11-15). This
is not hot reload.ADR 0005 (superseded) assumed a cdylib compiled UI
swapped by the host via libloading. A Slice 0 viability spike
(spec 0004, Linux x86_64, Wayland/niri, rustc 1.99.1, debug,
gpui = "=0.2.2", libloading = "0.8.9") found that mechanism infeasible for GPUI view/render
code on the current stack:
dlopen/dlclose mechanics work for isolated C-ABI symbol calls, but mounting GPUI views from a
separately loaded library into a host-owned GPUI application is incompatible with GPUI 0.2.2’s
type/instance model (Window::replace_root<E: Render> generic root, AnyView/Entity<V>
downcast and host App entity storage, thread-local element arena, TypeId identity, upstream
GPUI rlib-only).cdylib (trivial view change, 429 MB debug artifact) warm-relinked in
~171 s wall / 2m50s cargo in the spike run, far outside the < 500 ms budget.cdylib/libloading swap for GPUI view code is rejected unless new evidence resolves mount,
type/instance identity, unload safety, and measured performance.
Follow-up throwaway prototypes (Linux x86_64, Wayland/niri, rustc 1.99.1/cargo 1.99.1, debug
debug = 0, warm dx serve --hot-patch, gpui = "=0.2.2", subsecond 0.7.10,
dioxus-devtools 0.7.10, dx 0.7.10, not integrated into auro crates/CLI) evaluated same-process
function-level hot-patching of the tip crate:
subsecond::HotFn::current(...) boundaries in reloadable
view code, dioxus_devtools::connect_subsecond()/devserver patch application, host-owned GPUI
Application/window/event loop and entity state (ticker-updated counter, stable host string) kept
in the same process/type universe.HotFn patch observed at ~125 ms (rev=0→rev=1, counter
continued). GPUI 0.2.2 app warm view edits measured ~271-450 ms save-to-first-new-render with
host state preserved (s1: median 371.5 ms, N=10, values 438/409/371/422/372/406/339/343/350/300;
s6: median 346 ms, N=20, 20/20 stable). Helper/layout/style changes, coordinated transient struct
layout changes, multi-module tip-crate edits (functionally applied), build/syntax-error recovery,
and non-dx instrumented run were demonstrated.Render impl outside HotFn
and running ticker future unchanged). Tip-crate statics/render-local counters reset on patch
(host entity state preserved). thread_local! used in a patched path can fail patch generation
(R_X86_64_TPOFF32/-shared) while the app stays alive on previous code. dx/target-dir
isolation and build artifact contention require care.auro dev, and not proven across platforms/profiles.HotFn mechanism was validated on Windows 11 Pro 10.0.26200.0 x64
(rustc/cargo 1.99.0 MSVC, dx/subsecond/dioxus-devtools 0.7.10) with
dx serve --hot-patch --interactive false --platform desktop, a clean target, and external logs.
Build completed in 30.66 s and 3/3 warm src\main.rs hot-patches applied in 484/504/499 ms with
monotonic counter continuity rev=0 1..361 -> rev=1 421..781 -> rev=2 841..1261 -> rev=3 1321..1741
in the same process (ERR_LEN=0, plain-proofwin-20261116152539.*), demonstrating mechanism
viability on Windows x86_64 for this minimal plain case only (not a D6 benchmark). Caveats:
corrupted reused target (libdeps-62094602.a: unknown file type), inconclusive hidden/background
runs, and watcher noise from in-project verbose log redirection.HotFn::current(render_frontend) with
host-owned state (session, items, backend_ticks) and an init-captured backend thread.
View edits applied in 590 ms (ui0→ui1) and 523 ms (ui1→ui2 with added
radius/padding/icon) while session=s5500, items 4→36 and backend_ticks 8→72 stayed
continuous in the same process. A source change to the backend interval (500→1500 ms) was
hot-patched (527 ms) but the running task kept active_interval_ms=500; restarting with the
changed source produced a new process (session=s9516, init_backend_ms=1500) and a 1500 ms
tick cadence (adv-fix-20261116161242.*, adv-fix-restart-20261116161242.*, ERR_LEN=0). This
is the observed hot-boundary versus init-captured split for this mechanism, not a Tauri
backend-process comparison./RU pdl /IT): 206 [hot_view] renders, counter 0→204,
stable=host-owned-state preserved, no panic. The same exe launched from SSH/session 0 panicked
with Creating DirectX renderer → Creating DirectX resources → 0x887A0022
(DXGI_ERROR_NOT_CURRENTLY_AVAILABLE), as did dx serve --hot-patch from that context after a
199.20 s build. A dx serve --hot-patch run in the interactive session itself (scheduled task,
SESSION=1, clean target-gpui-hot3) built in 473.85 s, rendered (label=v0, counter 0→43),
applied its first patch (Hot-patching: src\main.rs took 1453ms, [patch_applied] t_ms=5760)
and then died with thread 'main' has overflowed its stack / exit code: 0xc000041d before any
label=v1 render (gpui-hot3-20261116-170828.*). Follow-up isolation on the same guest: the jump
table itself is sound (runtime dump: entries=746, aslr_ref=0xcab0/new_base=0xcb10 as RVAs,
exe exporting main at RVA 0xcab0), the crash reproduces with a 16 MiB main-thread stack
(/STACK:16777216, PE-verified), a leaf HotFn (fn(u64) -> u64) patched twice in one process
without crashing (bumped=1050 at counter 50, bumped=2193 at counter 193), and a
framework-free ViewData boundary reloaded UI values twice (1324 ms, 1084 ms) with
data=v1→data=v2, 120/187 renders after each, counter 4→175, stable preserved, no crash —
visually confirmed by a QMP screenshot of the same window (gpui-hot7-20261116-175144.*). The
Windows patch DLL is 89,600 bytes with only main exported and no GPUI/imports from the exe, so
the observed limit is consistent with the patch unit not carrying the framework. Windows GPUI
render works in an interactive session; view-code hot patching is blocked, framework-free hot
boundaries work.[dev] hot = true now runs a usable loop rather than a patch that needed a click to appear:
Hot-patching ... took, handler fired) with no visible change; this is also
the mechanism behind the earlier Windows "boundary never ran" observation. auro::hot::install
now registers a subsecond handler that bumps a revision and prints auro:trace hot_patch <n>;
App::try_run polls it (16 ms) on the main thread and calls cx.notify(root_entity) for every
open window, so the next frame runs the patched boundary.auro::hot::hot/hot_with print auro:trace hot_render <n> on the first
call after a patch. A view that validates the frame first (the generated one does) calls
hot_frame and rendered only after the frame is accepted, so a rejected frame does not produce
a render marker. auro dev combines its own save timestamp, the devserver's
Hot-patching ... took line and this marker into one JSON line per edit
(save_to_patch_ms, patch_to_render_ms, save_to_render_ms, patch_took_ms).data/src is a hot boundary edit. A save in ui,
types, the bin, a dependency, a manifest or the profile is labelled outside the hot boundary;
auro dev restarts the devserver and app, restores the snapshot and labels the outcome
restarted (state restored|reset), never as a reload. The previous app stays visible while the
replacement builds; a failed host rebuild keeps that UI running and is reported, and boundary
build errors also keep the previous UI. This makes the documented reload unit visible and gives
host-code changes the documented fallback instead of a silent no-op.view_data() -> HotData returns plain data; element and
layout code in Render is host-stable. Only functions reached through hot/hot_with consult
the jump table, so a patch of render alone does not change the running UI; auro dev restarts
the devserver/app for that host-code save. The scaffold prints the boundary's returned value per
revision so a boundary reload is visible.Cargo.toml defines [profile.desktop-dev] with
inherits = "dev", debug = 0, incremental = false. The Dioxus CLI uses that adhoc profile for
dx serve; debug_assertions remain on, which subsecond requires. DWARF dominated the relink
(3.3 s → ~0.5 s save-to-render on the demo), and disabling the incremental session was faster and
steadier for the one-file ThinLink rebuild.types (ViewData + fixed
HotData), data (the boundary), ui (Render, window, element tree, snapshot/autosave) and a
thin bin. ui does not depend on data, so dx recompiles the changed boundary crate and the
bin, not GPUI or the view. The patch library falls from roughly the size of the app to ~12 KB, and
the measured Linux median fell from 521 ms to 368 ms (N=12, 325-394). A plan struct boundary
without the fixed-frame check measured 288 ms; the guard costs ~80 ms and is kept because it
rejects a patch built against a changed data layout instead of letting the old host read it.auro::hot opens the devserver connection itself. A patch that fails to
load is caught (error or loader panic), reported, and the previous jump table keeps running; the
listener stays open for the next edit. The dev loop labels it patch rejected by the app, never
as a reload. A committed patch wakes the main thread through a watch channel instead of a 16 ms
poll, so patch-to-render is 1-26 ms and an idle app does not wake twice a frame.Linux measurement, earlier single-crate scaffold (niri/Wayland, x86_64, 12 CPUs, rustc 1.99.1,
gpui 0.2.2, dx/subsecond/dioxus-devtools 0.7.10, warm dependency cache, boundary-only edits):
save-to-render 473/488/519/521/521/522/528/539/548/567/572 ms (median 521 ms, min 473, max 572,
N=11); patch-to-render 8-24 ms; same pid and host state across patches. With incremental = true
the same app measured median 650.5 ms (N=10, 547-1722).
Linux measurement, four-crate scaffold (2026-11-18): save-to-render
393/371/385/370/366/339/357/370/394/350/325/366 ms (median 368 ms, min 325, max 394, N=12),
patch-to-render 1-26 ms, patch_took 268-325 ms, same pid/window/host state. The host was under
load average ~16 from an unrelated workspace test build for the series, so the numbers are
conservative for this machine. A type error kept the previous UI and the fixing edit applied in
270 ms (simple-frame series). A schema change applied as a patch was rejected by the running view
and left the previous values on screen.
HotData template then
measured 851/765/768/880/813/897/816/752/768 ms (N=9, median 813, min 752, max 897;
patch-to-render 2-16 ms) through auro dev, same pid/window, patch DLL 14,848 bytes. Defender
exclusions for the app and repo left four steady patches at 719-735 ms (one 1293 ms outlier);
incremental = true measured 830/848/799/819 ms steady (N=4); codegen-units = 1 measured
810/748/769/738/719 ms (N=5, median 748). The remaining gap is MSVC compile/link, not repaint,
the incremental session or codegen-unit count. dx serve must run inside the interactive
session (a session-0 run fails before render with DirectX 0x887A0022). Defender exclusions for
the project/cargo/rustup directories are recommended, but in this run they left four steady
patches at 719-735 ms (one 1293 ms outlier), not enough to reach the target. rust-lld linked a
plain cargo build but dx 0.7.10 rejected the hot patch with Missing linker args for fat link;
its fat-link interception requires the default linker, so lld is not a usable lever. /OPT:REF
plus /OPT:ICF measured a 767 ms median save-to-render (N=4), no gain. A ui/src/lib.rs save
restarted the devserver/app in 5.91 s with a new pid and restored snapshot; a following data
edit patched in 910 ms, and a syntax error kept the previous app and printed host rebuild failed; previous UI still running. The data boundary is the reloadable unit; Windows cannot
patch element-returning code.Hot reload macOS benchmark) measured the
guarded scaffold on a shared macos-26-arm64 runner with the prebuilt dx 0.7.10: six warm-up
edits then twelve measured, save-to-render
536/520/444/625/1071/598/481/507/439/512/462/372 ms (N=12, median 509.5, min 372, max 1071;
patch-to-render 2-17 ms), same process/window. A first cold run measured median 515 (N=12,
431-715). The runner is noisy and the median is slightly above target; five of twelve warm edits
were under 500. A second six-warmup run measured a 837.0 ms median (N=12, p95 2096, 583-2096) and
passed the host-restart check. A third, with the previous app kept alive during the rebuild,
measured 956.0 ms (N=12, p95 1563, 775-1563) and also passed restart. A twelve-warmup run measured
748.5 ms, so extra warm-up does not remove the variance; the three six-warmup runs span
509.5-956.0 ms and the target is not claimed met. Local hardware, signing and hardened-runtime
behaviour remain open.The < 500 ms reference case is met on Linux (median 368 ms), not on Windows (median 813 ms), and is above the target on a shared macOS runner (509.5 ms median; a second run measured 837.0 ms). It is reported per platform, never as a single global claim.
| Platform | Hot mode | Save-to-render (warm) | Evidence |
|---|---|---|---|
| Linux x86_64, niri/Wayland | Opt-in, verified | 368 ms median, N=12 (p95 394, 325-394) | Four-crate scaffold, desktop-dev, boundary edits, same pid/window/state |
| Windows 11 x86_64, MSVC | Opt-in, verified in interactive session | 813 ms median, N=9 (p95 897, 752-897) | Guarded four-crate scaffold, auro dev trace, same pid/window; still above target (a plain-boundary series measured 1168 ms) |
macOS arm64 (macos-26-arm64 runner) | Opt-in, measured in CI | 509.5 / 837.0 / 956.0 ms medians, three runs, N=12 after 6 warm-up (p95 1071/2096/1563) | Shared GitHub runner; host restart and snapshot restore verified; no local Apple hardware, signing or hardened-runtime test |
The host-code restart path is verified on Linux, Windows and macOS CI. macOS local hardware, signing and hardened-runtime behaviour remain unverified.
Per ADR 0008, the mechanism keeps one GPUI
Application/window/event loop and reloads updated UI code in the same process and type universe.
The implemented mechanism is subsecond/dx function-level patching of an explicit HotFn
boundary, with host-owned GPUI state and a versioned snapshot. The generated layout makes the
reloadable unit a small workspace crate (data) that the view crate (ui) does not depend on,
which keeps GPUI out of the patch and brings the Linux warm-edit median under 500 ms. The boundary
returns a fixed HotData frame so a changed data layout is rejected rather than misinterpreted.
The layout and fixed-frame decision is recorded in
ADR 0022; the contract, measurements and
remaining platform limits are in spec 0004.
Regardless of mechanism, reloadable state that opts in is captured as a versioned,
serde-compatible snapshot owned by the host before apply or before a state-preserving restart, and
restored after success. State that cannot be restored (incompatible version/key, non-serialisable
resource, or explicit reset) must be reported, never silently replaced. Tip-crate statics and other
patch-unit-local state must not be treated as preserved across an in-process patch.
When a change is not safely reloadable in-process (host/bootstrap/toolchain/config changes, failed compatibility/apply/patch generation, or mechanism limitations), the fallback is a state-preserving process restart: persist snapshot, restart, restore. Slower, but it preserves context and is labelled honestly.
dx/subsecond 0.7.10, gpui 0.2.2) the patched unit cannot construct GPUI
elements: an element-returning hot boundary applies and then overflows the main thread's stack.
The unit must return framework-free data (ViewData-style) that host-stable code turns into
elements; view-code hot reload there is unproven.HotFn consult the jump table. A function the framework calls
directly (the Render impl, element construction) is compiled into the patch but not invoked
through the jump table, so editing it leaves the running UI unchanged. The scaffold keeps the
element tree outside the boundary for exactly this reason.debug_assertions enabled: HotFn::try_call calls the local
function directly in release builds, so the jump table is bypassed and code changes silently do
not apply.types::HotData, a fixed #[repr(C)] frame with a schema number; change
ViewData and its encoder, bump SCHEMA, and never re-lay-out HotData.auro::hot handles apply_patch
errors and loader panics and keeps the previous jump table; the next edit can still apply.hot_frame in catch_unwind, reports a rejected frame and keeps the previous values; removing a
panic applied in 327 ms in the same process.[dev] hot = true; open: change classification for edits outside
the boundary (currently a patched, unchanged boundary), forced fallback restart, and a headless
reload fixture.data/ui/types/bin shape is implemented and
documented, including migration for older scaffolds; the author contract for larger reloadable
units is open. Edits outside data restart the devserver/app and restore the snapshot.Status: audit of the pinned stack on 2026-11-18. This page records what Auro and GPUI 0.2.2 actually provide. It is not a support claim.
auro-ui currently ships one primitive, Button, and no text-input primitive. The button:
There is no accessibility tree, no screen-reader bridge and no AccessKit integration in Auro.
Adding a fake one would mislead users; the gap is upstream.
A source audit of gpui 0.2.2 (the pinned version) found:
| Area | Present in GPUI 0.2.2 | Notes |
|---|---|---|
| Accessibility/AccessKit | No | No accesskit or accessibility symbol in the crate source or features |
| Text input handler API | Yes | platform::InputHandler, Window::set_input_handler/take_input_handler, ElementInputHandler |
| IME candidate positioning | Yes | InputHandler::bounds_for_range/PlatformWindow::update_ime_position |
| macOS IME | Yes | NSTextInputClient with insertText:replacementRange: and setMarkedText:selectedRange:replacementRange: |
| Windows IME | Yes | WM_IME_STARTCOMPOSITION/WM_IME_COMPOSITION handling |
| Wayland IME | Yes | zwp_text_input_v3 |
| X11 IME | Yes | XIM handler |
That means IME plumbing exists at the toolkit layer on all three target platforms. Auro does not wrap it in a widget, and no Auro test drives a composition event end to end. An app that uses GPUI's text elements directly inherits that plumbing; an app that wants an Auro-owned text field does not have one yet.
| Platform | IME plumbing | Screen reader | Verified in Auro |
|---|---|---|---|
| Linux (Wayland) | zwp_text_input_v3 | none | no |
| Linux (X11) | XIM | none | no |
| Windows | WM_IME_* | none | no |
| macOS | NSTextInputClient | none | no |
"Verified in Auro" means a maintainer ran a composition against an Auro app. No such run exists,
so the row stays no even though the upstream code path is present.
Button.Re-audit when the GPUI pin moves. A row moves to "verified" only after a real desktop session on that platform exercises composition and, for accessibility, a platform accessibility inspector reports the expected tree. CI compiling the code is not evidence for either.
Architecture decisions live here as short, numbered records. They exist so that a contributor - or an AI assistant - can tell the difference between "this is how it works" and "this was chosen, and here is what it costs".
Every record has the same four sections:
| Section | Content |
|---|---|
| Status | Proposed, Accepted, Superseded by NNNN, Deprecated |
| Context | the forces at play, without advocacy |
| Decision | one sentence, then what it implies |
| Consequences | what gets easier, what gets harder, what is now forbidden |
A record is immutable once accepted. To change a decision, write a new record that supersedes it; do not edit history.
Write a record when a choice:
Do not write one for naming a private function, choosing a test helper, or anything a Cargo.toml
diff explains better than prose.
An accepted RFC that changes the architecture produces an ADR. The RFC keeps the discussion; the ADR keeps the conclusion.
| # | Decision | Status |
|---|---|---|
| 0001 | Tauri's app model, GPUI's renderer | Accepted |
| 0002 | Rust-only frontend and typed IPC | Accepted |
| 0003 | Capabilities at the real boundary | Accepted |
| 0004 | Main thread belongs to GPUI | Accepted |
| 0005 | Hot reload with state preservation | Superseded by 0008 |
| 0006 | Dual MIT/Apache-2.0 | Accepted |
| 0007 | No styling language in 1.0 | Accepted |
| 0008 | Hot reload mechanism revised after feasibility spike | Accepted |
| 0009 | Toolkits are the application's choice | Accepted |
| 0010 | Typed events, delivered on the main thread | Accepted |
| 0011 | Bundling delegates to tauri-bundler | Accepted |
| 0012 | Release trust: Ed25519 manifests, delegated platform signing | Accepted |
| 0013 | AppImage updates: in-place replacement with a backup receipt | Accepted |
| 0014 | Platform updates use the native installer or bundle swap | Accepted |
| 0015 | Restart through the app executable and a durable journal | Accepted |
| 0016 | Delta patches are base-bound; rollout is deterministic | Accepted |
| 0017 | Linux package elevation is explicit pkexec, never self-root | Accepted |
| 0018 | Package rollback requires an explicit older artifact | Superseded in part by 0021 |
| 0019 | macOS package elevation uses an explicit AppleScript prompt | Accepted |
| 0020 | Notarization uses a keychain profile through notarytool | Accepted |
| 0021 | Opt-in rollback after a failed package apply | Accepted |
| 0022 | Hot reload boundary is a separate crate with a fixed frame | Accepted |
| 0023 | The update journal is a local trust boundary | Accepted |
Status: Accepted
Desktop apps in Rust face a choice between two mature, wrong-shaped options. Electron packs a browser: ~180 MB idle, ~900 ms cold start, ~120 MB binary. Tauri keeps an excellent application model - config, capabilities, plugins, bundling for seven package formats, signed updater, dev server, single-instance, multi-window - but renders the app as a web page in the system webview.
GPUI is Zed's GPU-accelerated Rust UI toolkit: pure Rust, a builder API, no DOM, no GC, no CSS engine. It arrived solved for text, IME, selection and font rendering, because it was a text editor first.
The parts of Tauri worth keeping are boring and expensive to rebuild. The renderer is the part worth replacing.
Auro is Tauri's application shell with GPUI as the renderer. The app model, CLI verbs, config shape and packaging surface follow Tauri; the UI layer is GPUI, and the frontend language is Rust.
Easier
Harder
Forbidden
Status: Accepted
Tauri's default IPC is invoke("save_document", { path, body }): the command name is a string,
the payload is JSON, and a typo surfaces as a runtime error in a browser console. The type
information exists at compile time in the Rust command, but it is discarded at the boundary.
Auro has no JavaScript. If the frontend is Rust and the backend is Rust, the boundary can be a function call. Serialisation is still needed for plugins and for persisted state, but not for first-party UI-to-command traffic.
Schemas are derived from Rust signatures (schemars), the call site is a plain async fn, and
there is no stringly-typed command dispatch in first-party code.
#[auro::command]
async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> { /* ... */ }
let saved = api::save_document(doc.path, doc.body).await?;
Easier
invoke string table, no payload casing mismatches, no "command not found" at runtime.Harder
Serialize/Deserialize/JsonSchema bounds on command arguments,
which some types do not satisfy cheaply (closures, borrowed data, platform handles).Forbidden
serde implementations whose field names diverge from the schema.Status: Accepted
Tauri's capability system exists because a web page is untrusted code sharing a process with
privileged commands. Auro's first-party frontend is Rust compiled into the app: calling
std::fs::write is not a privilege escalation, it is the app doing its job.
Copying Tauri's model wholesale would produce a permission system with no adversary, which trains users to click "allow" and reviewers to ignore the manifest.
The genuine runtime boundaries are narrower: third-party plugin code, untrusted content, and the future webview escape hatch.
Capabilities guard plugins, content, and the webview escape hatch - not first-party app code.
Grants are deny-by-default, declared in a manifest with scopes (fs, net, shell, clipboard,
notification, keychain), compiled into the host, and checked at the call site that performs the
effect.
Easier
Harder
cdylib) share the address space, so a capability check cannot contain a
malicious library. Defaulting to out-of-process is a consequence, not a preference.Forbidden
Status: Accepted
GPUI runs a single application loop and expects UI mutation on that thread. At the same time, an application framework must run file I/O, network requests, subprocesses and parsing - none of which belong in a render function.
The two requirements conflict unless there is exactly one rule about who may touch what.
GPUI owns the main thread; all UI mutation happens on it; all blocking work happens on the
tokio runtime; auro-ipc is the boundary between the two.
Easier
async fns, testable without a renderer.Harder
cx.update / AsyncApp::update), which is
more ceremony than a shared Mutex<State>.await, so data must be cloned out
first.Forbidden
blocking HTTP clients, Command::output or sleep on the main thread.Entity from a worker thread.static cache of entity handles, which becomes a use-after-free when the UI cdylib is
reloaded.Status: Superseded by 0008 - Hot reload mechanism revised after feasibility spike
Rust compile times are the only real reason a developer stays on the web. Tauri's edit loop is fast because the frontend is a script; Auro's frontend is Rust, so the loop is the product.
A 20-second cargo build between edits would make the rest of the framework irrelevant for anyone
doing UI work.
The UI compiles as a cdylib, the host loads it with libloading, and a successful rebuild
hot-swaps the renderer while app state survives as a serde snapshot. The target is
≤ 500 ms from save to visible change. Function-level patching (subsecond-style) is an
optimisation on top of the swap. If the target is missed, the documented fallback is a
state-preserving process restart, labelled as such.
Easier
Harder
libloading boundary: symbols, breakpoints and backtraces need work.dlclose semantics with live threads are a known hazard.Forbidden
statics.Status: Accepted
The README already states dual licensing under MIT or Apache-2.0, and the roadmap lists the licence
as an open question with the same recommendation. Rust's ecosystem, including cargo itself and
most of the crates Auro will depend on, is dual-licensed this way. A framework that expects
commercial desktop apps must not create licence friction for them, and Apache-2.0 supplies an
explicit patent grant that MIT alone does not.
Auro is licensed under MIT OR Apache-2.0, at the user's option. Every crate declares
license = "MIT OR Apache-2.0" in its manifest. Contributions are accepted under the same terms.
Easier
Harder
Forbidden
license = "MIT" or license = "Apache-2.0" alone on any crate in the workspace.Status: Accepted
Every GUI framework that grows a stying language eventually maintains two type systems: one for what the program computes and one for what the stylesheet says. Web developers arriving at a Rust UI toolkit will ask for CSS, or for a CSS-like DSL, because that is how they know to express layout.
GPUI's model is a builder API: div().flex().flex_col().gap_2().p_4(). It is Rust all the way
down, which means layout participates in normal tooling - autocomplete, types, refactoring.
The roadmap names scope drift into "CSS for Rust" as a project risk and committed to a hard rule.
Auro ships no styling language in 1.0. Styling is expressed in Rust against design tokens. Theming is data (tokens, light/dark palettes, TOML themes), not a syntax to be parsed.
Easier
Harder
Forbidden
.css-like file format, a selector engine, or a cascade in 1.0.Status: Accepted (supersedes 0005)
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:
dlopen/dlsym/dlclose of versioned C-ABI cdylib artifacts worked for symbol
calls, including a 429 MB debug cdylib that statically linked GPUI (load/unload cycles and A/B
copy swaps returned; dlclose returning is necessary but not sufficient proof of safe unload
under a live GUI/session with threads, TLS, and platform resources).Window::replace_root is generic over the concrete Render root type; AnyView stores an
entity plus a monomorphized render::<V> path that downcasts to Entity<V> and updates the view
in the host App entity map; AnyElement is arena-backed in a thread-local element arena; and
entities/refcounts depend on TypeId and host App storage. 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).cdylib (trivial string change
in a view) took 2m50s cargo / ~171 s wall in the spike run (full relink of a 429 MB debug
cdylib, with package-cache/build-dir lock contention noted). Toy comparisons rebuilt in 1.81 s
(monolithic GPUI bin), 0.60 s (trivial GPUI-dependent cdylib export), and 0.17 s (no-dep
cdylib), showing that artifact split alone is not sufficient and a realistic view library relink
is prohibitive for the < 500 ms budget.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.
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".cdylib that 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.auro dev remains 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.Easier
Harder
Forbidden
cdylib swap for GPUI view code without new evidence that resolves the
type/instance, mount, unload, and performance constraints recorded in spec 0004.Status: Accepted (2026-11-17)
Phase 1 planned an auro-ui component kit of about twenty widgets. Before implementing it, we
evaluated adopting gpui-component instead, because it
already ships 60+ widgets and would remove a large chunk of work.
The decision has to hold three constraints:
gpui = "=0.2.2" is the line that carries the
hot-reload evidence (subsecond/dx 0.7.10, function-level patching, state preservation).
Moving the renderer line is a separate, expensive decision.A throwaway spike on 2026-11-17 (Linux x86_64, Wayland/niri, rustc 1.99.1, release, stripped,
panic = "abort", one window with a label and one button) measured:
| Probe | Stripped binary | spawn → window requested (median, N=5) |
|---|---|---|
Auro with its own Button | 15.5 MB | 139.8 ms |
GPUI + gpui-component 0.5.0 (Root + Button) | 22.0 MB | 147.3 ms |
The delta is +6.5 MB (+42%); startup is effectively unchanged. The component probe compiled
and opened a window against the pinned gpui 0.2.2. It added 46 packages, including non-optional
tree-sitter, html5ever, ropey, markdown, lsp-types and rust-i18n, and 58k lines of
source. It is not only a widget crate: it requires gpui_component::init(cx) and wrapping every
window root in Root::new(view, window, cx), and it owns a global theme, dialog/notification state
and input focus.
Version compatibility matters as much as size:
gpui-component | GPUI line | Consequence |
|---|---|---|
| 0.5.1 (2026-02-05) | gpui ^0.2.2 | last line that compiles against Auro's pinned renderer |
| 0.6.0 and later | gpui-pre ^0.3.1 | requires a GPUI line migration; current 0.10.0 pins gpui-pre =0.3.12 |
Adopting the current component line therefore means moving the GPUI pin and revalidating the hot-reload bet. Adopting the compatible line means freezing nine-month-old widgets with no upstream fixes on our pin.
Both measured binaries are far above the 6 MB target, so size work is needed regardless; adding
6.5 MB makes that target harder, not easier. Writing the kit ourselves is not free either: the
useful subset for Phase 1 (Input, List, Table, Tabs, dialogs, menus) is an estimated
5-8k lines, and input/table are the hard parts.
Auro ships no component toolkit. Toolkit choice belongs to the application.
auro-ui stays the renderer seam: GPUI re-exports, Auro tokens, and the minimal primitives the
scaffold and tests need. It does not gain a component kit in 1.0.App::setup, and wraps its root in the toolkit's shell with
App::root_with when the toolkit needs one.App::setup receives the parsed Config, so the app can apply app.windows[].theme to the
toolkit it chose. Auro does not own a theme system.gpui-component 0.5.x while GPUI 0.2.2 is pinned — and
says plainly that the current component line requires a GPUI migration. No toolkit is a
framework dependency.Alternative rejected: own the twenty widgets. It preserves size and API ownership but spends the phase on a toolkit Auro says it is not, and duplicates a mature library.
Alternative rejected: adopt gpui-component into auro-ui. It wins schedule but costs 6.5 MB on
every app, freezes a stale line or forces a GPUI migration that invalidates the hot-reload
evidence, and makes a pre-1.0 third-party API Auro's public component API.
Easier
Harder
Forbidden
auro-core or auro-ui as a framework dependency.Button as a component kit.An optional integration crate (for example auro-gpui-component) can wrap the current toolkit
line without changing this decision: the framework core still ships no toolkit.
Status: Accepted (2026-11-17)
Phase 1 needs app-wide events: a command finishes an import, a background task makes progress, a
view wants to announce something to other views. The project forbids stringly-typed dispatch
(ADR 0002) and requires UI mutation on the GPUI main thread (ADR 0004). Commands run on Auro's
tokio runtime, so a background producer cannot touch App, entities or windows directly.
Options considered:
emit/listen shape). Rejected: a renamed event becomes a silent
runtime no-op, which is the failure mode Auro exists to remove.EventEmitter only. Useful for parent/child wiring, but a command has no
entity and app-wide delivery would still need a fan-out mechanism.TypeId, with a main-thread pump. Chosen.auro-core owns a renderer-agnostic channel. Any E: Send + 'static can be emitted.
EventSender is cloneable, Send + Sync, and auto-managed in the state store, so a command can
take State<EventSender> and call sender.emit(event). It boxes the event with its TypeId and
queues it on an unbounded tokio::sync::mpsc channel. emit returns false when the app is
gone.EventBus global and a foreground pump. The pump awaits the receiver and
dispatches each event on the main thread through AsyncApp::update.App::on_event::<E>(|event, cx| ...) registers a handler before the app runs. Handlers are
keyed by TypeId, run in registration order, and receive &mut App so they can update entities
and call cx.notify(). A panic propagates.emit(event, cx) is the main-thread path and dispatches synchronously. Background producers must
use EventSender.RefCell borrow.Ordering is FIFO per producer through the queue. A main-thread emit can interleave with queued
events; there is no total order across producers. The queue is unbounded and has no backpressure in
this slice.
Easier
Harder
Forbidden
tauri-bundlerStatus: Accepted (2026-11-17)
Phase 2 must produce .app/.dmg, MSI/NSIS, AppImage/deb/rpm. Writing and maintaining a bundler
means WiX, NSIS, macOS bundles, codesign/notarization plumbing, Debian/RPM metadata, AppImage
tooling and platform edge cases: months of work that is not the product. The roadmap already says
Auro keeps Tauri's packaging model; the only question is which implementation.
Options:
auro-bundle from scratch. Rejected: enormous platform surface, not differentiating.tauri-bundler behind auro-bundle. Chosen.cargo-bundle. Rejected: less coverage of Windows installers and Linux packaging.tauri-bundler 2.10.5 is Apache-2.0/MIT, the same dual-license family as Auro, and the roadmap
already commits to wrapping it. Its own documentation warns that minor releases may change the
public API.
auro-bundle pins tauri-bundler = "=2.10.5" and maps the validated Auro.toml [bundle]
section onto its Settings.
AuroError::Bundle.auro bundle builds the release binary and delegates artifact creation to the bundler; it does
not reimplement packaging.bundle.targets = "all" resolves to the host set; cross-compilation is not a
supported Phase 2 workflow.tauri-bundler is a deliberate change that must pass the three-OS CI, because a minor
release may change the API.Easier
Auro.toml).Harder
AuroError::Bundle, not hidden.Forbidden
tauri-bundler stops supporting a platform Auro targets, or its API churn becomes unmanageable.Status: Accepted (2026-11-17)
Phase 2 needs two different trust problems solved:
tauri-bundler
already drives these platform tools and exposes the settings/environment hooks (ADR 0011).Options for update authenticity:
auro-sign provides Ed25519 keys, detached signatures and SHA-256 file hashes. Secret keys are
32-byte base64 seeds in a 0600 text file; public keys and signatures are base64. Verification is
strict (malleable signatures rejected).[bundle.macos] and [bundle.windows] map signing inputs onto tauri-bundler; Auro does not
invoke codesign/signtool itself. Notarization credentials stay in the environment.auro-update defines manifest format v1. The signature covers the manifest payload excluding the
signature field; size and SHA-256 cover the artifact. The client format is Auro's, independent of
Tauri's updater.Easier
Harder
Forbidden
Status: Accepted (2026-11-17)
The updater stages a signed, verified artifact (spec 0013).
Applying it differs per distribution: Linux AppImages are one executable file, Windows uses MSI or
NSIS installers, macOS bundles need bundle-level replacement, and .deb/.rpm updates belong to a
package manager.
Options for the first apply path:
.deb/.rpm. Out of scope: it needs elevated privileges and
distro-specific behavior.On Linux, AppImageInstaller replaces an AppImage atomically: keep the old file as a hard-link
backup (copy fallback), write the staged artifact to a temporary file in the target directory, set
mode 0755, sync, and rename it over the target. It returns an InstallReceipt; the caller must
either discard the backup after verifying the new version or rollback it. Dropping the receipt
does not delete the backup.
Compiled only on Linux. Other platforms and package formats get separate apply contracts; there is no generic installer-command hook. Installing does not restart the app.
Easier
Harder
Forbidden
Status: Accepted (2026-11-17)
The updater now has a verified staged artifact (spec 0013). Linux AppImages are replaced in place (ADR 0013). Windows and macOS have different artifact shapes and privilege models:
.app from a staged zip.
Chosen for the next apply layer..dmg images or delegate to a package manager. Deferred: both need more platform
setup and privilege handling.Windows apply runs the staged MSI through msiexec /i <artifact> /qn /norestart, or the staged NSIS
installer with /S, using an injected, shell-free InstallerRunner. Exit 0 succeeds; 3010 and
1641 succeed with restart_required; every other code is InstallerFailed.
macOS apply accepts a staged .zip with exactly one top-level .app, extracts it with the zip
path sanitizer, rejects symlinks that resolve outside the extraction tree, renames the old bundle
to a hidden backup beside the target, renames the new bundle into place, and returns a receipt that
can roll back or discard the backup. No installer waits for the app to exit, restarts it or requests
elevation.
Easier
Harder
.dmg/.pkg, code-signing checks, package-manager updates and restart orchestration remain
separate work.Forbidden
.dmg/.pkg, .deb/.rpm or delta/rollout apply changes the artifact shape.Status: Accepted (2026-11-18)
After an apply, the running process must not launch its replacement itself: the new process would race the old one, and the old process may still need to flush state. A helper must wait for the app to exit, then launch the replacement. Options:
ApplyJournal records the applied version, artifact, optional target/backup, relaunch command and
state. spawn_helper takes an exclusive sibling lock and spawns the current executable with
AURO_UPDATE_RESTART_HELPER pointing at the journal. On Linux the relaunch command prefers
$APPIMAGE; current_exe() would name the temporary AppImage mount. App::try_run recognizes that variable before config/GPUI and waits for the old process to release
the lock. A Prepared journal with an ApplyKind is verified against the app-provided public key and applied
through the platform installers (specs 0014/0025); the backup is recorded and the journal becomes
Applied (or RebootRequired when Windows asks for a reboot); an Applied journal is
relaunch-only. The helper then launches the recorded command with the helper variable removed.
The helper process is detached into its own process group. A failed apply writes Failed and never
relaunches. Because helper re-exec happens after apply, the executable at the relaunch path after
the swap must honor the same environment/journal contract.
Easier
Harder
App::try_run/App::run for helper mode to exist.spawn_helper leaves a journal to inspect, not an automatic recovery.Forbidden
Applied.Status: Accepted (2026-11-18)
The updater can verify and stage full artifacts, but the roadmap calls for deltas and staged rollout. Both change the signed manifest shape and both have failure modes that can strand or fragment an install:
Manifest format v2 adds optional signed delta and rollout fields. Deltas are
bsdiff-4-compatible patches (qbsdiff), bound to the running version and base SHA-256; the patch
size/hash and resulting full artifact size/hash are verified before staging. A caller can fall back
to a full download explicitly.
Rollout uses a caller-supplied stable install key and a SHA-256 bucket over key, version and artifact hash. 0 holds, 100 admits, and a partial percentage without a key holds. The selection is deterministic; the manifest is the only rollout control plane in this slice.
Easier
Harder
Forbidden
Status: Accepted (2026-11-18)
Spec 0027 deliberately ran dpkg/rpm as the current user and left elevation out. That is safe but
incomplete: installing a package needs root, and simply running the whole app as root spreads the
privilege across UI, network and update code. A package manager also executes maintainer scripts,
so the boundary must be explicit and auditable.
The alternatives are a root-owned helper (best long-term isolation, needs installation/polkit
policy), sudo (TTY/password semantics, not desktop-friendly) and pkexec (standard polkit, desktop
agent). The first is more work than this slice; the second is a poor fit for a GUI app.
The restart helper uses pkexec with absolute paths and an argument vector:
/usr/bin/pkexec /usr/bin/dpkg -i /proc/<helper-pid>/fd/<fd>
/usr/bin/pkexec /usr/bin/rpm -U /proc/<helper-pid>/fd/<fd>
The helper opens the already-verified staged artifact and keeps the read-only descriptor alive while
pkexec runs. Elevation is opt-in through LinuxPackageInstaller::elevated(); new() remains the
unprivileged path. Any non-zero pkexec result is ElevationFailed, the journal records Failed,
and the app is not relaunched. Auro does not roll back package-manager transactions.
Easier
Harder
pkexec, /proc and a polkit agent are runtime dependencies on Linux.Forbidden
setuid.sudo, or an auto-elevated package path.Status: Accepted (2026-11-18)
The Linux package path can install .deb/.rpm files and elevate through pkexec. A bad update
still needs a way back. The operating system package manager has no generic previous-version store:
dpkg and rpm own their databases, caches are optional local state, and a downgrade can break
dependencies. An automatic rollback would have to invent a safe old package and decide when it is
valid.
LinuxPackageInstaller::rollback accepts a caller-supplied, already-staged older package. It runs
dpkg --force-downgrade -i or rpm -U --oldpackage, reusing the same elevation and held-descriptor
semantics as install. Auro does not download, discover or repack the old package, and does not
automatically invoke rollback on failure.
The caller remains responsible for authenticating the rollback artifact through the same manifest
path and for deciding whether the downgrade is safe. ApplyJournal::mark_rolled_back is available
but is not wired to a failure hook.
Easier
Harder
Forbidden
-U/-i invocation.Status: Accepted (2026-11-18)
A .pkg needs /usr/sbin/installer and, for a system install, administrator rights. The app
process must not become root. macOS offers no stable, simple direct elevation API: sudo assumes a
terminal, Authorization Services is deprecated, and a signed privileged helper is a separate
installation and trust project. The standard desktop authorization sheet is exposed through
AppleScript's do shell script ... with administrator privileges.
MacPkgInstaller::elevated() runs /usr/bin/osascript with a fixed run handler. The staged path
is passed as an argument and quoted form quotes it for the one shell command; no untrusted path is
inserted into script source. The app remains the user and the installer runs as root only after the
system prompt. Direct installer execution remains available as MacPkgElevation::None.
The macOS installer owns its package transaction. Auro records failure, does not relaunch, and does not roll back or repair dependencies. Notarization and Gatekeeper policy remain separate.
Easier
.pkg can be applied with the standard macOS authorization sheet.InstallerRunner on any host.sudo credential cache, or custom helper is required for this slice.Harder
osascript and a GUI authorization session are runtime dependencies.Forbidden
setuid.sudo as a silent or terminal-dependent fallback.notarytoolStatus: Accepted (2026-11-18)
macOS releases need a notarization ticket, but Apple credentials are secrets and Auro has no
business storing them. notarytool supports a login-keychain profile, and stapler attaches the
ticket to a .pkg, .dmg or zipped artifact. The alternative is to hide notarization inside a
bundler invocation, which makes network/credential failures look like packaging failures and forces
an Apple account onto every local bundle.
auro notarize takes an artifact and an existing keychain profile. MacNotarizer runs
xcrun notarytool submit ... --wait followed by xcrun stapler staple ... through an injectable,
shell-free NotarizeRunner. Submission and stapling are separate and explicit; --skip-staple
defers the second step. Auro never handles the Apple password, API key or profile creation.
Notarization is release hardening. It does not replace the signed update manifest, artifact hash or Auro signature, and the command does not claim Gatekeeper acceptance without a real Mac check.
Easier
auro bundle stays offline and usable without an Apple account.Harder
auro bundle and real Gatekeeper verification remain future work.Forbidden
Auro.toml, source or argv.auro bundle gains an opt-in notarization phase..app signing/stapling policy is specified.Status: Accepted (2026-11-18)
ADR 0018 gives the Linux package path an explicit rollback operation but forbids invoking it automatically, because Auro cannot invent a safe previous package. It closes with a revisit condition: "the apply journal gains an explicit rollback plan and failure hook".
The journal now carries that plan when the caller supplies one. The remaining question is whether a package-manager failure should use it automatically, and on which failures.
A .deb/.rpm ApplyPlan may carry a PackageRollback: an already-staged older artifact, its
signed manifest and the app's pinned key. If the primary apply fails with InstallerFailed, the
helper re-verifies that package, requires a strictly lower version and the host platform, runs the
elevated downgrade, marks the journal RolledBack, and relaunches the old app without overwriting
that state.
The hook runs only on InstallerFailed. ElevationFailed (the user declined or pkexec could not
execute), a missing/tampered artifact, a platform mismatch, a version that is not older, and any
non-package apply do not trigger it. To make that distinction real, pkexec codes 126/127 (or no
code) stay ElevationFailed; other non-zero codes are the child package manager's status and are
InstallerFailed.
The caller still chooses and supplies the older package. Auro never queries a package cache, retains a previous package or decides that a downgrade is dependency-safe.
Easier
Harder
Failed journal.Forbidden
RolledBack, not Applied.This record supersedes only the "does not automatically invoke rollback on failure" and "no automatic failure hook" sentences of ADR 0018; its artifact contract and downgrade flags remain.
Status: Accepted (2026-11-18)
ADR 0008 selected same-process function-level patching
with an explicit HotFn boundary and left the project layout open. The first integrated scaffold
put the boundary and the GPUI view in one bin crate. dx recompiles a changed crate and its
dependents, so every boundary edit recompiled and relinked the view, and the patch library carried
GPUI: the measured Linux median was 521 ms and each apply mapped an app-sized library.
A patch also has to agree with the host that is already running. A typed boundary returning a locally defined struct is fine while the two layouts match, but a freshly compiled patch can return a different layout while the old host reads the old one. That is undefined behaviour, not a diagnostic.
The generated app is a four-crate workspace:
| Crate | Contents | May depend on |
|---|---|---|
types | ViewData and the fixed HotData frame | nothing |
data | the hot boundary view_data() -> HotData | types |
ui | Render, window, element tree, snapshot/autosave | auro, types, serde |
| bin | main calling ui::run(data::view_data) | ui, data |
ui never depends on data. A boundary edit therefore recompiles data and the thin bin, not
GPUI or the view. The dependency direction is a tested invariant, not a convention.
HotData is a fixed #[repr(C)] frame with a schema number, title length and accent. The host
checks schema and bounds before decoding; a changed schema is rejected and the previous values stay
on screen. Change ViewData and its encoder, bump SCHEMA, and never re-lay-out HotData.
auro::hot::hot_frame/rendered report a render only after the view accepts the frame.
auro::hot owns the devserver connection. apply_patch errors and loader panics are caught and
reported; the previous jump table keeps running and the listener stays open. A committed patch
wakes the main thread through a watch channel rather than a poll.
Easier
data restarts the devserver/app and restores the snapshot; it is labelled as a
restart, never as a reload.Harder
ui to data undoes
the fast path; a scaffold test fails if it happens.HotData is an ABI: its shape is frozen and changes require a restart/version bump.incremental and Defender exclusions did not close the gap. The
relaunch loop remains the Windows fallback.Forbidden
ui -> data or data -> auro dependencies in the generated layout.HotData's shape without treating it as an ABI change.Status: Accepted (2026-11-18)
The update journal is a small JSON file that names a verification key, a staged artifact, a platform target, a backup and a relaunch command. The restart helper reads it after the old process exits and applies the plan. Re-verifying the artifact with the key inside the journal proves that the two agree; it does not prove who wrote the journal.
A journal planted by another local user can therefore choose its own key, artifact and executable. On a package apply that plan reaches an elevation prompt with an attacker-supplied package. The journal and its lock therefore need a directory that only the current user can write.
Rust's standard library exposes ownership and modes on Unix, but not Windows ACLs. A check that is
only cfg(unix) would leave the Windows helper with no protection and would make the API's safety
property platform-dependent in an undocumented way.
ApplyJournal validates the journal's local trust boundary fail-closed on every load, save and
helper lock open. Unix checks the effective owner, group/other write bits, symlinks and ancestors
on opened handles. Windows opens the reparse point itself, rejects reparse attributes, and checks
the owner and DACL for write/delete/ACL grants to principals other than the current user, SYSTEM,
Administrators and the creator-owner SIDs. A path that cannot be proven private is
UpdateError::JournalTrust; there is no bypass in the public API.
The library does not claim more than it proves: the Windows tests run on GitHub Actions
windows-latest and pass, but Windows ancestors are not walked, and a verify-then-open window
remains for staged artifacts consumed by an external installer.
Spec 0033 records the tests and limits; metadata
freshness, rotation and revocation are not solved by this decision and are modelled in
RFC 0001.
0700 and files 0600 on Unix, so an umask of 000 does
not silently widen the journal.A specification describes what a slice of work must do and the contracts it must satisfy, precisely enough that implementation is mechanical. It is not a proposal and not a decision record.
| Document | Question it answers | Mutability |
|---|---|---|
ROADMAP.md | what ships in which phase, and the exit criteria | living |
| spec (here) | what exactly must exist, with which interfaces and acceptance checks | living until the phase closes |
| ADR | why a choice was made, and what it costs | immutable once accepted |
| RFC | a design that needs discussion before it is decided | frozen at decision |
A spec that changes an architectural decision needs a superseding ADR in the same pull request. A spec that adds scope beyond the phase it belongs to needs an RFC first.
Every spec carries:
Draft, Approved, Implemented, Superseded by NNNN| # | Spec | Phase | Status |
|---|---|---|---|
| - | What Auro takes from Tauri | evidence | living |
| 0001 | Foundation: workspace, runtime seam, commands, state, dev loop | 0 | Implemented |
| 0002 | Auro.toml schema, merge rules, validation | 0 | Implemented |
| 0004 | Hot reload: save-to-visible with preserved state, measurability, mechanism under revision | 1, 3 | Draft - opt-in hot mode integrated; Linux 368 ms median (target met), Windows 813 ms (above), macOS 509.5 ms on a shared CI runner (boundary) |
| 0005 | Toolkit seam: setup hook, app-owned root, no framework toolkit | 1 | Implemented |
| 0006 | Lifecycle events: ready, window open/close, exiting | 1 | Implemented |
| 0007 | Typed application events: sender, main-thread pump, handlers | 1 | Implemented |
| 0008 | Command schemas: input/output metadata on the handler | 1 | Implemented |
| 0009 | Window manager: open/close/focus by configured label | 1 | Implemented |
| 0010 | Bundling: map [bundle] to tauri-bundler, host formats, auro bundle | 2 | Implemented (Linux, Windows and macOS verified) |
| 0011 | Signing keys, artifact hashes, platform signing config | 2 | Implemented |
| 0012 | Signed update manifests: format, verify, CLI | 2 | Implemented (v2; 0013 stage, 0028 deltas/rollout) |
| 0013 | Updater runtime: check, download, verify and stage | 2 | Implemented (full/delta; 0014/0025 apply) |
| 0014 | AppImage apply: atomic replacement and rollback receipt | 2 | Implemented (Linux only) |
| 0015 | Single instance: advisory lock, argument forwarding | 2 | Implemented (opt-in activation helper) |
| 0016 | Capability manifests and enforcement | 2 | Implemented (host wiring pending) |
| 0017 | Autostart service | 2 | Implemented |
| 0018 | Notifications service | 2 | Implemented |
| 0019 | Keychain service | 2 | Implemented |
| 0020 | Global shortcuts service | 2 | Implemented (pressed callbacks) |
| 0021 | Tray service | 2 | Implemented (icons, menus and click callbacks) |
| 0022 | Deep links: scheme registration, parsing and queue | 2 | Implemented (initial and forwarded wiring) |
| 0023 | Keyboard activation for Button | 2 | Implemented (AccessKit/IME pending) |
| 0024 | Alpha release: version, publish order, facade features, scaffold | 2 | Draft (alpha candidate; publication pending) |
| 0025 | Windows installer execution and macOS .app replacement | 2 | Implemented (.dmg and macOS elevation separate) |
| 0026 | Update journal and restart helper | 2 | Implemented (helper applies, relaunches, reconciles) |
| 0027 | Linux .deb/.rpm package apply | 2 | Implemented (elevation in 0029) |
| 0028 | Binary deltas and deterministic staged rollout | 2 | Implemented |
| 0029 | Linux package elevation through pkexec | 2 | Implemented |
| 0030 | Linux package rollback with an explicit older artifact | 2 | Implemented (manual policy) |
| 0031 | macOS .pkg apply through installer/osascript | 2 | Implemented in tree (runtime unverified) |
| 0032 | macOS notarization submission and stapling | 2 | Implemented in tree (credentials/runtime unverified) |
| 0033 | Update journal trust boundary: fail-closed ownership/mode/ACL checks | 2 | Implemented (Unix tested; Windows compile-verified, runtime unverified) |
Evidence for the foundation spec. Studied source: tauri-apps/tauri at
commit 3aac98b (2026-11-13), crate versions 2.12.x; published versions checked on crates.io on
2026-11-15.
The rule this document applies: copy the shape, depend on the parts that are expensive and webview-free, and never depend on anything that carries a web engine into our build graph.
| Crate | Reusable? | Why |
|---|---|---|
tauri-bundler | Yes, as a dependency | No tauri dependency; the only Tauri crate it needs is tauri-utils for config/resource types (crates/tauri-bundler/Cargo.toml:18). Webview coupling is three narrow spots: the WebView2 installer plumbing, a webkit2gtk file copy in the AppImage, and the __TAURI_BUNDLE_TYPE binary patch, which degrades to a warning |
tauri-macos-sign | Yes, later | Codesign/notarize helpers with no webview involvement (crates/tauri-macos-sign) |
tauri-utils | Shape only | Webview-free (manifest has no wry/webkit/tao), but it is a heavy dependency: HTML parsing (kuchikiki/dom_query), aes-gcm, brotli, plist, cargo_metadata (crates/tauri-utils/Cargo.toml:16-53). We want its ideas - config schema, ACL - not its 30 transitive crates |
tauri-macros | Shape only | Emits code against ::tauri paths and says "Don't depend on this crate directly" (crates/tauri-macros/src/lib.rs:7). It supports root = "crate" (src/command/wrapper.rs:45), but generate_handler! also calls tauri_utils::acl::read_allowed_commands (src/handler.rs:103), so reuse drags tauri-utils into the proc-macro |
tauri-runtime | No | Not webview-free at the crate level: unconditional webkit2gtk, webview2-com, gtk (crates/tauri-runtime/Cargo.toml:41-46), and gtk::ApplicationWindow leaks into WindowDispatch and RawWindow (src/lib.rs:788-798, src/window.rs:655) |
tauri-runtime-wry | No | It is the webview (pub use wry, src/lib.rs:98) |
tauri-codegen | No | Embeds assets, hashes/compresses them, injects CSP (crates/tauri-codegen) - all webview concerns |
tauri | No | wry is a default feature (crates/tauri/Cargo.toml:185-192); PlatformWebview exposes the raw webview (src/webview/mod.rs:153-195) |
tauri-cli | Shape only | Its command set and dev flow are the reference; the code is tied to tauri-build/tauri-codegen |
tauri-plugin | Shape only | Plugin builder/hooks are generic enough to imitate |
| Tauri | Auro | Note |
|---|---|---|
#[tauri::command] + generate_handler! | #[auro::command] + auro::generate_handler! | Same authoring experience; the wrapper emits a __cmd__<fn> macro and a command-name macro (crates/tauri-macros/src/command/wrapper.rs:155,297) |
CommandArg / IpcResponse / InvokeError | same names, our traits | JSON assumptions are confined to three blanket impls (crates/tauri/src/ipc/command.rs:196-335); our first-party path is an in-process typed call |
Manager::manage + State<'_, T> | same | State is resolved per command from the app handle |
tauri.conf.json sections (app, build, bundle, plugins) | Auro.toml sections (app, dev, bundle, plugins) | TOML instead of JSON, build renamed to dev, webview keys dropped |
capabilities/*.json + tauri-utils ACL resolution | same file format and resolution idea | Scopes stay data; enforcement stays at the call site |
bundle_project(&Settings) | auro_bundle::bundle(&Config) mapping into that call | Our config stays ours; the mapping is one module |
tauri-runtime is not an abstraction we can adopt; Auro writes
its own Runtime-shaped seam over GPUI. The trait shape (window dispatch + handle) is still
the right model.tauri-bundler's Settings and its
per-OS tool matrix (codesign/dmg, WiX/makensis, AppImage/deb/rpm) buys years of edge cases.tauri-bundler 2.10.4 declares rust-version = "1.90", edition
2024 (crates/tauri-bundler/Cargo.toml:13-14); the same floor applies workspace-wide in Tauri
(Cargo.toml:45-46).crates/tauri-bundler/src/lib.rs:9-14). Pin the minor and treat an
upgrade as a change that needs a CI run on all three platforms.tauri/tauri-utils/tauri-runtime at 3.0.0-alpha
while the stable line is 2.10-2.12. Depend on the 2.x line, pinned, and do not chase the alpha.Studied gpui 0.2.2 (crates.io, 2026-10-30), edition 2024, license Apache-2.0, no declared
rust-version.
Application::new().run(|cx: &mut App| ...) with cx.open_window(WindowOptions, |window, cx| cx.new(|cx| View::new(cx))) (examples/hello_world.rs, src/platform.rs:1089).Render::render takes &mut Window: fn render(&mut self, window: &mut Window, cx: &mut Context<Self>).Context::spawn takes AsyncFnOnce(WeakEntity<T>, &mut AsyncContext) (src/app/context.rs:237),
and spawn_in adds the window (src/app/context.rs:661).ViewContext no longer exists (0 occurrences in the crate). The sample in our README and
roadmap was written against a pre-0.2 GPUI and does not compile; it is corrected with this spec.gpui-component 0.9.1 (repo longbridge/gpui-kit) ships 75+ components, AccessKit roles, and
headless UI integration testing. The Phase 1 "~20 components" plan was revisited in ADR 0009:
the toolkit is the application's choice, not a framework dependency.tauri dev is an orchestrator, not a code generator: resolve dirs, load and merge config
(helpers/config.rs:143-223), rewrite Cargo.toml feature lists from config
(interface/rust.rs:140-158), run beforeDevCommand, pick a runner, optionally start a built-in
static file server (dev.rs:235-265), wait for the dev URL, watch folders
(dev.rs:99-327). There is no frontend bundler in the CLI.tauri-build is a build-script helper for platform metadata, resources and ACL; context/assets
codegen is opt-in behind a codegen feature (tauri-build/src/lib.rs:481-489,932-939).tauri-codegen and is one branch of the generated Context
(tauri-codegen/src/context.rs:176-207). The seam is context_codegen with
ContextData::assets: Option<Expr> and a re-rootable root: TokenStream
(tauri-codegen/src/context.rs:37-42,134).auro dev
is: build the app crate, spawn the binary, watch, kill, rebuild, relaunch. Build-time codegen is
needed only for the capability manifest and the embedded config, and both can start as runtime
loads instead.Tauri's ACL is separable from the webview, and Auro keeps its file format and resolution model.
identifier, description, local, remote, windows,
webviews, permissions, platforms (crates/tauri-utils/src/acl/capability.rs:117-215).
windows and platforms apply to Auro unchanged; webviews and remote do not exist here.capabilities/**/*.{json,json5,toml} next to the app crate
(crates/tauri-build/src/acl.rs:437-459). An explicit list in the config replaces discovery.default, set and permission; a permission names commands
with allow/deny and scope with allow/deny values (crates/tauri-utils/src/acl/manifest.rs:19-46,
src/acl/mod.rs:181-221). Deny wins over allow.capabilities.json, acl-manifests.json and
allowed-commands.json in OUT_DIR (crates/tauri-build/src/acl.rs:432,472,482); the runtime
only evaluates the resolved structure.tauri-build's Cargo-feature rewriting and generate_context! re-rooting: Auro's build story is
a plain cargo build plus, later, a generated capability manifest.Status: Implemented (Phase 0 closed 2026-11-17)
Phase 0 exists to answer one question: does an Auro app feel like a native app, and is the loop fast enough to live in? This spec defines the smallest set of contracts that makes the vertical slice real, and nothing beyond it.
Auro.toml: the configuration surface an app author edits (fields in 0002).auro new, auro dev, auro build, auro doctor.#[auro::command], generate_handler!, AuroError.< 500 ms target and mechanism are tracked in spec 0004.$schema generation and build-script codegen. Config loads at
runtime until the bundler lands.Phase 0 materialises auro (facade), auro-core, auro-ui, auro-ipc, auro-macros,
auro-cli. auro-bundle joins in Phase 2 (spec 0010); auro-perms, auro-plugins,
auro-update, auro-sign arrive with the phase that needs them.
Rejected: creating all nine empty crates now. Empty crates invite speculative APIs and make the
workspace look finished when it is not. Rejected: folding IPC into auro-core. The command
boundary is the thing the project is built around; it gets its own crate from day one.
| Crate | Kind | Depends on | Responsibility |
|---|---|---|---|
auro | lib | core, ui, ipc, macros | App builder, window attachment, prelude; the only crate an app depends on |
auro-core | lib | ipc | config loading, state store; re-exports the IPC runtime; no renderer types (lifecycle and events in Phase 1) |
auro-ipc | lib | - | CommandArg, IpcResponse, Invoke, registry, AuroError, tokio runtime bridge |
auro-macros | proc-macro | - | #[command], generate_handler! |
auro-ui | lib | core | the only crate that names gpui; primitives, tokens, Render re-export; themes are toolkit-owned (ADR 0009) |
auro-cli | bin | core | new, dev, build, doctor; no runtime logic |
Rules: no cycles; auro-ui holds no policy (no filesystem, no config reads); gpui is a
dependency of exactly one crate (auro-ui), and app-level tests enable its test-support feature
through a dev-dependency; auro-core never names a renderer type. The builder lives in the facade
because it is the one place that must know both the app model and the renderer.
Rejected: the builder in auro-core. It would force gpui into core's manifest or a
renderer-abstraction trait layer that buys nothing in Phase 0.
gpui = "=0.2.2" # in auro-ui only
Edition 2024, resolver 3, workspace MSRV 1.90 (the floor tauri-bundler 2.10 declares).
Exact pins, not ranges: GPUI is pre-1.0 and breaks on minor bumps. Upgrading is a deliberate
change with a changelog entry, not something cargo update does behind our back.
Rejected: a git dependency on Zed's main. It turns every cargo build into a lottery and is
how a compat layer becomes a fork.
GPUI ships its own executors (smol-based). Context::spawn polls on the main thread; nothing in
GPUI runs a tokio reactor. A command body calling tokio::fs from GPUI's executor panics with
"no reactor running".
Therefore #[auro::command] is a code transform, not metadata: it wraps the body in
auro_ipc::runtime::run(async move { /* body */ }) (re-exported as auro_core::runtime) and awaits
the task, so the body always runs on Auro's multi-threaded tokio runtime no matter who awaits it. A
sync command runs through runtime::run_blocking. The runtime is a process-global LazyLock
created on first use, so tests and first-party call sites work without App::run.
The other rules:
!Send and never cross threads.Send + 'static; results come back through
Entity::update / AsyncApp::update, then cx.notify() schedules the repaint.await inside a command must not hold an entity borrow.Rejected: one thread per command. Unbounded, untraceable, hostile to cancellation. Rejected:
running commands on GPUI's executor. tokio APIs would panic, and blocking work would stall the
window.
#![allow(unused)] fn main() { #[auro::command] async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> { /* ... */ } }
name = "...", rename_all = "snake_case" | "camelCase" (default
snake_case). Async is detected from the async fn itself. A plain fn is allowed: it is emitted
as an async fn and its body runs on the blocking pool, so a first-party call site always awaits
an off-thread result.serde::Deserialize + Send + 'static, or State<T>. The Phase 1 command registry
adds schemars::JsonSchema for schema derivation; Phase 0 has no schema consumer.Result<T, AuroError> with T: Serialize + Send + 'static.generate_handler![save_document, load_document] builds a CommandHandler that maps a command
name to a typed dispatch. In Phase 0 it exists and is tested; it is not wired into App.
Wiring arrives with plugins, when something other than first-party Rust calls it.api::save_document(...)); the handler is
the boundary for the future plugin and webview paths.AuroError is #[non_exhaustive] with From<std::io::Error> and From<serde_json::Error>.Rejected: reusing tauri-macros with root = "::auro". The macro also pulls
tauri_utils::acl::read_allowed_commands at expansion time, so reuse buys a proc-macro dependency
on a crate that is about to jump to 3.0.
App::manage(value) stores T: Send + Sync + 'static behind an Arc.State<T> is a cheap owned handle (Arc<T>, Deref<Target = T>), not State<'_, T>: a
borrowing handle cannot be captured by the Send + 'static command future. The macro resolves
State arguments before hopping to tokio, so the body receives the owned handle.auro-core, emitted through the app handle; that
contract lands with the Phase 1 lifecycle work. Window events stay GPUI events. No untyped
broadcast payloads.Rejected: a global EventBus with string topics. It is the failure mode the project exists to
avoid. Rejected: State<'_, T> copied from Tauri. Tauri's commands can borrow because its
invocation runs on a different boundary; ours cannot.
Auro.toml next to the app's Cargo.toml; TOML; sections [app], [dev], [bundle]; platform
overrides in Auro.<platform>.toml merged key by key. Full field table,
defaults and validation rules: 0002.
app.identifier, app.product-name,
app.version and the window list come from the file. The builder attaches root views to windows
by label: App::new().root::<Editor>("main").run().AURO_CONFIG (a path), then Auro.toml in the current directory, then in
the directory of the running executable. A missing file is an error with exit code 2 that names
both places searched.AURO_CONFIG_OVERRIDES, a JSON Merge Patch. There
is no other CLI-to-app channel.app.version versus Cargo.toml is checked by auro build and auro dev (which have the
manifest), not by the running app.App::run(self) prints the AuroError diagnostic (configuration, platform or instance) and
exits 2; App::try_run(self) -> Result<(), AuroError> is the non-exiting entry point (tests drive
views through GPUI's TestAppContext instead). On Linux, try_run rejects a Wayland compositor
that does not advertise the globals GPUI 0.2.2 binds, so a minimal compositor gets a typed error
instead of a panic.Loaded at runtime in Phase 0. Embedded at bundle time in Phase 2, when there is a bundler to embed it into.
Rejected: the Rust builder owning identity and window geometry. It makes Auro.toml decorative
and splits one truth across two files.
auro dev = load config, cargo build, spawn the binary with AURO_CONFIG_OVERRIDES, watch
src/** and Auro.toml, kill, rebuild, relaunch. Ctrl-C stops the child and exits 0. No dev
server, no frontend directory, no static file serving.
Rejected: starting with hot reload before the app model was proven. A relaunch loop proves the app model without risking the schedule; the hot-reload mechanism is tracked in spec 0004.
Phase 2 wraps tauri-bundler (2.10.x, pinned) behind auro-bundle, mapping our [bundle]
section into its Settings. It is the one Tauri crate we depend on. Its own docs warn that minor
releases may change the API, so an upgrade is a change that must run the three-OS CI.
Rejected: writing a bundler. .dmg + codesign/notarize + WiX + NSIS + AppImage + deb + rpm is
months of edge cases that are not the product.
GPUI 0.2.2 has no max-size, no always-on-top, no per-window theme setter, and its decorations
switch is platform-specific. Phase 0 maps size, position policy (center), minimum size,
resizability, visibility, fullscreen, transparency and decorations onto WindowOptions. theme
is parsed and handed to the app through App::setup; the chosen toolkit applies it
(ADR 0009). The remaining keys are parsed,
validated, and reported by auro doctor as "accepted, not honored on this platform". A config
key that silently does nothing is worse than one that says so.
Rejected: implementing platform-specific window code in Phase 0. It is a Phase 2 item, and it
belongs in auro-ui with the rest of the renderer.
| Command | Behaviour |
|---|---|
auro new <path> | scaffold the tree below; refuse a non-empty directory |
auro dev | build, spawn, watch, relaunch |
auro build | cargo build --release; no packaging until Phase 2 |
auro doctor | toolchain, GPUI pin, config parse result, platform, Linux dependencies, and config keys the platform cannot honor |
auro --version | the workspace version |
The scaffold is the four-crate workspace from
ADR 0022; types is framework-free, data owns
the hot boundary, ui owns the view, and the bin wires them.
demo/
Auro.toml
Cargo.toml # auro in-repo path or published version; workspace members and profiles
Dioxus.toml # `dx serve` name for hot mode
icons/icon.png # 512x512 placeholder; replace before release
src/
main.rs # demo_ui::run(demo_data::view_data)
ui/
Cargo.toml # depends on auro and types, never on data
src/lib.rs # Render, window, element tree
src/services.rs # command functions, the `api` module the UI calls
data/
Cargo.toml # depends on types only
src/lib.rs # the hot boundary
types/
Cargo.toml # no dependencies
src/lib.rs # ViewData and the fixed HotData frame
The bundler slice extends the scaffold with the placeholder icon and [bundle] icon; apps replace
it with their own asset. auro new does not create empty asset directories.
use auro::prelude::*;
#[auro::command]
async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> {
tokio::fs::write(&path, body).await?;
Ok(Saved { path, bytes: body.len() })
}
impl Render for Editor {
fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
div()
.flex()
.flex_col()
.gap_2()
.child(Button::new("save", "Save").on_click(cx.listener(
|this, _, _window, cx| {
let doc = this.document.clone();
cx.spawn(async move |this, cx| {
let saved = api::save_document(doc.path, doc.body).await?;
this.update(cx, |this, cx| {
this.status = format!("Saved {} bytes", saved.bytes);
cx.notify();
})
})
.detach();
},
)))
.child(self.status.clone())
}
}
fn main() {
auro::App::new()
.root::<Editor>("main")
.run();
}
The window comes from Auro.toml; main names it by label. This is the current GPUI 0.2 API:
render receives &mut Window, listener closures take (this, event, window, cx), spawn
yields (WeakEntity<T>, &mut AsyncApp), and WeakEntity::update takes any AppContext. The
sample in README.md is corrected from this spec.
Runnables, in order, on a clean checkout:
cargo build --workspace --locked succeeds on Linux, macOS and Windows.cargo run -p auro-cli -- new /tmp/demo creates the tree; cargo check inside it passes.cargo run -p auro-cli -- dev inside /tmp/demo opens the window declared in Auro.toml; the
button dispatches an async command and the rendered text changes; closing the window exits 0.auro dev leaves no child process behind.cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked pass.State extraction, sync
and async dispatch through CommandHandler, AuroError conversion, and auro new refusing a
non-empty directory.TestAppContext, await the command task, assert the view's status field, and assert the
rendered tree contains that text via debug_bounds. GPUI has no text accessor, so the field is
the contract and the tree check is structural.Phase 0 accepted on 2026-11-17: all eight items below are met. The closing audit fixed
auro build's manifest parse (it failed on every app), wired the version check into auro dev,
added the executable-directory config fallback, validated [bundle] targets against the host, made
auro doctor report the resolved GPUI pin, and added the config round-trip and AuroError
conversion tests the specs required.
ubuntu-latest and ubuntu-22.04 (latest:
runs 44004201364/44004201288 for ff96535; earlier run 43776830848 for 5a5d389 remained
the first green after adding libxkbcommon-x11-dev). Local gates are green on the closing commit./tmp/auro-demo builds) and on Windows 11 (auro new then cargo build in
274 s in the guest), after fixing two scaffold defects found there: a backslash path that TOML
rejected as a unicode escape, and a missing [workspace] that let a parent manifest capture the
app.#[auro::command] and asserts the view update
(auro integration test clicking_button_dispatches_async_command_and_updates_view). Closing
the last window now quits the app and was verified to exit 0 on a local niri/Wayland session
(/tmp/auro-demo binary); closing through auro dev also exits 0 (measured 2026-11-16:
warm auro dev → window in 2 s, close → DEV_EXIT=0). Automated process-level window-close
coverage is the only test debt; the acceptance item is a manual runnable, verified as described.
The window-title gap observed on 2026-11-16 (niri/Wayland reported
(unset) although Auro.toml set one, while app_id was correct) was diagnosed and fixed the
same day: GPUI 0.2.2 applies WindowOptions::titlebar.title on X11, Windows and macOS but not on
Wayland, so App now calls Window::set_window_title when opening each window. Verified on
niri (title: "auro-demo" from niri msg --json windows) and covered by the headless unit test
app::tests::opens_window_with_the_configured_title.-D warnings, tests).State extraction, sync and async dispatch,
rename/unknown-command handling, AuroError conversion via ? for io and json, auro new
refusing a non-empty directory).auro-ui integration test root_view_renders_status_and_bounds renders a root view
through TestAppContext, asserts status == "Ready" and a non-empty rendered tree via
debug_bounds.niri msg windows by
app id, 50 ms poll resolution). A cold build of the demo (dependencies included) takes minutes, so
the number is only meaningful with a warm cache. Details and the trace format: spec 0004, D6.
Phase 0 required a recorded measurement; the < 500 ms target is spec 0004's and is not a Phase 0
exit condition.| Question | Where it settles |
|---|---|
Component kit: own primitives vs gpui-component | Resolved: Auro ships no toolkit; the app chooses one (ADR 0009, spec 0005) |
| Hot reload mechanism and its measurability | Spec 0004 |
| Plugin isolation: out-of-process first or in-process | Phase 3 RFC |
Does release embed config or ship Auro.toml next to the binary | Phase 2 spec |
| Windows/Linux input, IME and a11y parity | Phase 2 audit |
Status: Implemented (Phase 0 closed 2026-11-17; Phase 2 signing keys added in spec 0011)
Auro.toml is the only file an app author edits to describe their app. This spec fixes its
location, format, every Phase 0 key, the merge rules, and what makes it invalid.
Auro.toml at the app crate root, beside Cargo.toml.kebab-case (TOML idiom). Section and field names mirror Tauri's tauri.conf.json, so a
Tauri user recognises the shape; the case convention is the only translation. Mapping is
mechanical and lives in auro-bundle when it lands.Rejected: JSON. It is the format Tauri uses, but it costs comments and trailing commas for no benefit in a file humans maintain by hand. Rejected: TOML with camelCase keys. It satisfies neither idiom.
AURO_CONFIG (a path) if set, otherwise Auro.toml in the app directory (current directory,
or the one --dir names), falling back to the executable's directory.Auro.<platform>.toml where platform is macos, windows or linux, merged key by key.AURO_CONFIG_OVERRIDES, a JSON Merge Patch set by auro dev from --config key=value flags,
merged last. This environment variable is the only CLI-to-app channel. auro build gains
overrides with embedded config in Phase 2; a Phase 0 build has no runtime to hand them to.Merge is recursive for tables and replacing for arrays: a platform file that declares
app.windows replaces the list; it does not append to it. Merging arrays positionally is how
config systems become unreadable. The rule is JSON Merge Patch (RFC 7396) minus the null-deletes
case, which TOML cannot express.
auro dev --config uses the resolved config as a type hint. A field that is a string keeps a bare
123 as "123"; numeric, boolean, array and object fields parse JSON. A nullable field has no
value to hint from, so both the string and the JSON form are tried against the resolved Config:
Option<String> keeps 123 as a string and Option<u32> parses it as a number. Quoting the value
always produces a JSON string. Numeric path segments index arrays. Because a merge patch replaces
arrays wholesale, an indexed path seeds its array from the resolved config before changing one
element, so app.windows.0.width=800 keeps that window's label and the other windows. An index past the
resolved array is rejected: a patch cannot insert a TOML-null slot or invent a complete element.
null is rejected because TOML has no null value.
In Phase 0 the file is read at runtime. Bundled apps embed it in Phase 2.
app.windows is an array of tables; the first one is the default unless app.default-window
names another. Labels are unique and stable: they are what a capability targets later.
Required: app.identifier, app.product-name, app.version, and at least one window.
Top level also accepts "$schema" (string): an editor hint pointing at the published JSON Schema.
It is never read at runtime and never affects behaviour.
[app]| Key | Type | Default | Notes |
|---|---|---|---|
identifier | string | required | reverse-DNS, [A-Za-z0-9.-], no leading/trailing dot; becomes the bundle id |
product-name | string | required | window-title default and bundle display name |
version | string | required | SemVer; must match Cargo's concrete package.version (including version.workspace = true) or the build fails |
description | string | "" | one line, used by the bundle metadata |
authors | array of string | [] | "Name <email>" |
homepage | string | "" | URL |
license | string | "" | SPDX expression; must be compatible with MIT OR Apache-2.0 |
default-window | string | first window's label | must match a declared label |
[[app.windows]]| Key | Type | Default | Notes |
|---|---|---|---|
label | string | required | unique, [A-Za-z0-9_-] |
title | string | app.product-name | |
width | integer | 960 | logical pixels |
height | integer | 640 | logical pixels |
min-width | integer | none | |
min-height | integer | none | |
max-width | integer | none | |
max-height | integer | none | |
resizable | bool | true | |
decorations | bool | true | |
transparent | bool | false | |
always-on-top | bool | false | |
visible | bool | true | |
center | bool | true | |
fullscreen | bool | false | |
theme | "light" | "dark" | "system" | "system" |
[dev]| Key | Type | Default | Notes |
|---|---|---|---|
watch | array of string | ["src", "Auro.toml"] | paths relative to the app dir |
run-args | array of string | [] | passed to the spawned binary in relaunch mode; dx owns the process in hot mode and auro dev prints a note |
build-args | array of string | [] | passed to cargo build |
hot | bool | false | run dx serve --hot-patch instead of rebuild-and-relaunch; needs dx (dioxus-cli 0.7.x) on PATH or AURO_DX, plus the app's hot-reload feature. auro dev refuses with the missing feature named, and auro doctor reports availability. Patches are applied by dx, so run-args are not forwarded, target-dir builds belong to dx, and only code reached through auro::hot::hot/hot_with reloads in-process. The generated layout puts the boundary in data/src and reports it through hot_frame/rendered; edits outside data/src are host code and restart the devserver/app with the snapshot restored |
[bundle]Validated in Phase 0 and consumed by auro bundle (spec 0010) in Phase 2. Nothing here changes auro build.
| Key | Type | Default | Notes |
|---|---|---|---|
active | bool | true | |
targets | array of string | "all" | "all" | app, dmg, msi, nsis, appimage, deb, rpm; the list must be non-empty; unsupported per host is an error, not a skip |
icon | array of string | [] | first existing format wins per platform |
resources | array of string | [] | glob patterns, relative to the app dir |
category | string | "DeveloperTool" | Apple/XDG category name |
short-description | string | "" | installer metadata |
long-description | string | "" | |
copyright | string | "" | |
license-file | string | "" | shipped in the bundle when set |
[bundle.macos]Code signing and notarization inputs. tauri-bundler reads APPLE_ID, APPLE_PASSWORD,
APPLE_TEAM_ID (or the Apple API key variables) from the environment; those credentials are never
config keys. notarize-profile selects Auro's keychain-profile path instead.
| Key | Type | Default | Notes |
|---|---|---|---|
signing-identity | string | none | passed to codesign |
entitlements | string | none | plist path relative to the app dir |
hardened-runtime | bool | true | distribution default |
skip-stapling | bool | false | do not wait for/stapling the notarization ticket |
notarize-profile | string | none | xcrun notarytool keychain profile; auro bundle notarizes and verifies the produced .app/.dmg, and ignores the key on hosts that produce no macOS artifact (spec 0032) |
[bundle.windows]Authenticode signing inputs.
| Key | Type | Default | Notes |
|---|---|---|---|
certificate-thumbprint | string | none | SHA-1 of the signing certificate |
digest-algorithm | string | none | e.g. sha256 |
timestamp-url | string | none | timestamp server |
tsp | bool | false | RFC 3161 timestamping |
sign-command | string | none | custom signer; %1 in sign-args is the binary |
sign-args | array of string | [] | arguments for sign-command |
allow-downgrades | bool | true | allow an older version to replace a newer one |
webview-install-mode is not configurable: Auro has no webview and always skips WebView2.
Failures are AuroError::Config { path, key, message } and abort before a window opens. Rules:
app.version differing from Cargo.toml: reported by auro build and auro dev, naming both
values. The running app cannot see the manifest, so it does not perform this check.default-window naming nothing: error.bundle.targets naming a package format the host cannot produce: error listing the valid set
for that host. The known formats are app, dmg, msi, nsis, appimage, deb and rpm;
the host sets are macOS app/dmg, Windows msi/nsis, and Linux appimage/deb/rpm.
An explicit list that is empty is rejected; use "all" to request the host set.watch, icon, license-file, resources or bundle.macos.entitlements paths
escaping the app directory: error.width/height must be greater than zero; a set min-width/min-height/
max-width/max-height must be greater than zero, a minimum must not exceed its maximum, and
the initial size must lie inside the configured bounds.app.windows without a matching App::root/App::root_with is a typed
AuroError::Window before the event loop starts, not a headless process.# Auro.toml - the smallest valid file
[app]
identifier = "com.example.demo"
product-name = "Demo"
version = "0.1.0"
[[app.windows]]
label = "main"
title = "Demo"
width = 960
height = 640
pub struct Config { pub app: AppConfig, pub dev: DevConfig, pub bundle: BundleConfig }
impl Config {
/// Tries `AURO_CONFIG`, then `<dir>/Auro.toml`, then the executable's directory; merges the
/// platform file and `AURO_CONFIG_OVERRIDES`, validates, returns.
pub fn load(dir: &Path) -> Result<Config, AuroError>;
}
auro doctor lists the keys the current platform cannot honor.Auro.toml fails with exit code 2 and a message naming the paths searched.[app] fails with a message naming it.Auro.linux.toml overriding app.windows replaces the list; overriding app.product-name
changes only that key.version mismatch against Cargo.toml fails auro build and auro dev.Implemented and accepted with Phase 0. Coverage lives in auro-core/src/config.rs
(parses_the_minimal_file_and_applies_defaults, platform_file_replaces_arrays_and_merges_tables,
rejects_unknown_keys, missing_config_names_both_places_searched,
falls_back_to_the_executable_directory, rejects_a_bundle_target_this_host_cannot_produce,
every_documented_key_survives_a_round_trip), in auro-cli/src/project.rs
(refuses_a_config_version_that_disagrees_with_the_manifest, accepts_matching_versions), and in
auro doctor against a real app.
Status: Draft - opt-in hot mode integrated (four-crate data boundary; Linux median 368 ms, Windows 813 ms, macOS 509.5-956 ms across three shared CI runs); auro dev still relaunches by default
Spec 0001 closed Phase 0 with a relaunch loop and recorded ~60 s save-to-visible on the development machine (relink dominates). This spec defines the contract that must replace that loop for UI work: a long-lived dev host that applies reloadable UI changes while preserving restorable state, how save-to-visible is measured, and the fallback when a reload cannot be performed safely.
It realises ADR 0008
(ADR 0005, superseded, set the goal and assumed a
cdylib/libloading swap mechanism) and the
hot reload architecture. Where this spec learns from implementation
or research it must be corrected in the same pull request.
A time-boxed spike prototyped the previously drafted mechanism (host-owned GPUI application with a
separately built/loaded/unloaded reloadable UI cdylib exporting a C-ABI mount/snapshot/restore
contract) before committing implementation effort.
Environment: Linux 7.3.4-1-cachyos x86_64, Wayland/niri (DISPLAY=:0, WAYLAND_DISPLAY=wayland-1),
12 CPUs, 22 GiB RAM, rustc 1.99.1 (stable-x86_64-unknown-linux-gnu), cargo 1.99.1, debug profile,
warm incremental builds, gpui = "=0.2.2" (registry, rlib-only upstream crate), libloading = "0.8.9".
Observed:
| Area | Observation |
|---|---|
| Baseline (relaunch) | ~60 s save-to-visible, single visible change, relink dominates (spec 0001, 2026-11-15). Not hot reload. |
dlopen/dlclose mechanics (C-ABI symbols only, no live GPUI render/app task graph) | Load/unload, 3-5 cycle load/unload, and A/B copy swap simulations succeeded for a no-dependency cdylib and for a 429 MB debug cdylib statically linking GPUI (ABI symbol calls returned; dlclose returned). Necessary but not sufficient for safe unload under a live GUI session. |
| GPUI 0.2.2 mount boundary | Swapping/mounting GPUI view code from a separately loaded library into a host-owned GPUI application is not feasible under standard Rust/cargo builds. Window::replace_root is generic over concrete E: Render; AnyView stores a monomorphized render::<V> that downcasts to Entity<V> and mutates host App entity storage; AnyElement is arena-backed in a thread-local element arena; entities/refcounts use TypeId and host App maps. Upstream GPUI is rlib-only, so host and library carry separate GPUI instances/statics/type identities. Passing Rust/GPUI view/entity/element types across a C ABI is unsound/incompatible with normal view authoring. |
| Warm rebuild cost (trivial one-line string/view change, debug, after warm cache) | Monolithic GPUI bin: 1.81 s (1m30s initial). Trivial GPUI-dependent cdylib export (4.3 MB): 0.60 s (1m26s initial). No-dependency cdylib: 0.17 s. Realistic GPUI-view cdylib (div()/AnyElement, 429 MB debug): 2m50s cargo / ~171 s wall (full relink; package-cache/build-dir lock contention noted, link-dominated). |
| Unload safety | A GPUI-linked cdylib had TLS and init/fini arrays; live-window/task/thread/platform-resource behavior was not exercised. Safe quiesce/unload under a running GPUI app remains unproven even if symbol-only dlclose returns. |
Conclusion: the drafted cdylib/libloading swap of GPUI view/render code is rejected for the
current stack (GPUI 0.2.2, standard linkage). The observable hot-reload contract remains; the
mechanism must be revised (see D1).
Follow-up throwaway prototypes (not integrated into auro crates/CLI) evaluated the leading
same-process candidate on Linux 7.3.4-1-cachyos x86_64, Wayland/niri (:0/wayland-1), 12 CPUs,
22 GiB RAM, rustc 1.99.1/cargo 1.99.1 (stable), dx 0.7.10, subsecond 0.7.10,
dioxus-devtools 0.7.10, gpui = "=0.2.2" (registry, rlib-only), debug profile debug = 0, warm
dx serve --hot-patch, xattr patch as in workspace. Artifacts: /tmp/auro-option1-spike
(subsecond-plain, gpui-subsecond-spike, scenario logs/JSON).
Mechanism exercised: tip-crate function-level hot-patching (jump-table/ThinLink) with explicit
stable subsecond::HotFn::current(...) boundaries; dioxus_devtools::connect_subsecond();
host-owned GPUI Application/window/event loop and entity/managed state in the same process/type
universe (root entity counter ticker + stable host string).
| Case | Observation |
|---|---|
Plain Rust (non-GPUI) HotFn patch | rev=0→rev=1 in tip-crate function: Hot-patching ... took 125ms, output changed while loop counter continued (state/process preserved). |
| s1 warm latency/state, minimal GPUI app (N=10, sequential trivial label edits) | 10/10 visible, host counter/stable/pid preserved. Save→first-new-render: 438,409,371,422,372,406,339,343,350,300 ms (median 371.5, min 300, max 438). dx hot-patch: 351,328,326,322,322,304,289,297,293,284 ms. |
| s2 view/helper/layout/style (4 edits) | Helper-only change (label unchanged) 304 ms; label+added child 292 ms; style/bg 297 ms; helper+label 383 ms; helper changes visible; host state preserved. |
| s3 outside boundary / init not retroactive | Patches visible (314,321 ms), state preserved. Render impl change outside HotFn boundary not reflected in rendered stable value; init-created host state literal not retroactive. |
| s4 tip-crate statics/reset | Before: n=23 tip=1022 counter=19; first patched render: n=1 tip=1000 counter=24, stable preserved. Tip-crate counters/statics reset; host entity state preserved. |
| s5 build/syntax failure + recovery | Broken edit kept app alive on previous v0 with progressing counter (no crash/apply of broken code); fix patched (314 ms) to v1-fixed with n=1 tip=1000 counter=1247, state preserved. |
| s6 longevity (N=20) | 20/20 visible, all state preserved, final v20, same pid. Save→first-new-render median 346 ms (min 271, max 370). |
| s7 init-captured async work | Ticker-interval source edit (100→400 ms) patched but running ticker rate unchanged (~10.00→10.00 cps): captured future not retroactive. |
| s8 coordinated transient struct layout change | Added Vm field with coordinated construct/log/UI update in same edit: visible (362 ms), extra logged, counter progressed, no error. |
| s9 multi-module tip crate | Baseline ex=m0. Module-only edit visible as ex=m1 (269 ms) with host state preserved; module+main visible as v1 ex=m2; dx logged hot-patches for src/extra.rs and src/main.rs (functionally applied). |
| s10 no dx/devserver | cargo build + run without DIOXUS/devserver: alive, 59 renders, counter 0→56 progressed, no panic (SIGINT exit) - instrumented app runs without hotpatch tooling. |
s11 thread_local! in patched path | Failed to generate patch (rust-lld R_X86_64_TPOFF32 ... cannot be used with -shared), no patch applied, app stayed alive on v0 with progressing counter (honest failure). |
Conclusion: subsecond/dx tip-crate HotFn patching is a viable experimental same-process
candidate on Linux x86_64/GPUI 0.2.2 in minimal prototype conditions (sub-500 ms warm view edits
and preserved host state demonstrated), but not integrated into auro dev and not a D6 claim
for representative Auro scaffolds/apps or other platforms/profiles. Required follow-up: Auro project
layout/tip-crate/build strategy, host-owned versioned snapshot/restore and incompatible-change
classification/reset, auro dev opt-in integration (dx/devserver or equivalent driver, target-dir
isolation, timing/trace and diagnostics), and representative D6 measurements.
Windows plain prototype follow-up (2026-11-16, WinBoat guest, not integrated): a throwaway
non-GPUI Rust tip-crate prototype (same subsecond/dioxus-devtools/dx 0.7.10 HotFn
mechanism, dioxus_devtools::connect_subsecond(), and a HotFn::current(render).call((count,))
loop with [workspace] isolation) was validated on a Windows 11 Pro 10.0.26200.0 x64 guest
(WIN-30IUPGSQL9F, WinBoat VM, rustc 1.99.0/cargo 1.99.0 stable-x86_64-pc-windows-msvc, MSVC
Build Tools 14.44.35207, debug). With a clean target
(CARGO_TARGET_DIR=C:\Users\pdl\wvmt\op1win\target-plain-proof), external stdout/stderr logs, and
dx serve --hot-patch --interactive false --platform desktop, build completed in 30.66 s and 3/3
warm hot-patches of src\main.rs applied in 484 ms, 504 ms, and 499 ms with monotonic counter
continuity across revisions in the same process: rev=0 count 1..361 -> rev=1 421..781 -> rev=2 841..1261 -> rev=3 1321..1741 (30 sampled app lines, ERR_LEN=0; evidence:
C:\Users\pdl\wvmt\op1win\logs\plain-proofwin-20261116152539.*). This demonstrates the same-process
tip-crate HotFn patching mechanism works on Windows x86_64 in this minimal plain prototype (not a
D6 benchmark). An earlier observed run (transcript, artifacts cleaned) showed rev=0 count=541 -> 637 ms hot-patch -> rev=1 count=601 with continuity. Caveats: non-GPUI only; not integrated into
auro dev; not production/GA; not representative D6 for Auro scaffolds/apps. Observed failures/caveats: reusing corrupted target target-plain-dx3 caused
Failed to generate fat binary: rust-lld: error: ...\desktop-dev\libdeps-62094602.a: unknown file type; hidden/background dx runs were inconclusive (missing/0-byte logs in early attempts); and
in-project verbose log redirection produced watcher noise/misleading hot-patch labels.
Windows advanced front/back prototype (2026-11-16, WinBoat guest, plain non-GPUI, not
integrated): a second throwaway tip crate modelled a host-owned UI state plus an init-captured
backend task (a thread that reads its interval once at startup), with the frontend rendered through
HotFn::current(render_frontend) and printed state lines (session, items, backend_ticks,
init_backend_ms). Three edits inside the hot boundary applied as warm hot-patches of
src\main.rs: 590 ms (ui0 blue/120/Save/light → ui1 green/180/Salvar/dark), 523 ms
(ui1 → ui2 orange/240/Publicar/contrast, adding radius=12 padding=24 icon=rocket), and
527 ms (backend-interval source edit). Across all three the process and host state were
continuous: session=s5500, items 4→36, backend_ticks 8→72, same pid, init_backend_ms=500.
The backend source change (backend_tick_interval_ms 500→1500) was hot-patched but not
retroactive: the running backend task kept logging active_interval_ms=500 (18 tick lines after
the change, last ticks=69 active_interval_ms=500). A restart with the changed source produced a new
process (session=s9516, first render ui_v=ui2, init_backend_ms=1500) and a 1500 ms cadence
([backend_tick] ... ticks=1 active_interval_ms=1500, ticks 1→21 over ~30 s). Evidence:
C:\Users\pdl\wvmt\op1win\logs\adv-fix-20261116161242.* and
adv-fix-restart-20261116161242.*, ERR_LEN=0 in both phases. This is the observed
frontend-hot-boundary versus init-captured-backend split for this mechanism on Windows; it is not a
Tauri backend-process comparison and not a product contract.
GPUI 0.2.2 on Windows (2026-11-16, WinBoat guest, not integrated): the GPUI prototype
(gpui = "=0.2.2", subsecond/dioxus-devtools 0.7.10, host-owned RootView counter ticker and
stable string, HotFn::current(hot_view) in Render::render) built in 181 s
(target-gpui-win2\debug\gpui-subsecond-spike.exe, 23.9 MB). Launched through a scheduled task in
the active interactive console session (/RU pdl /IT, session 1) it rendered: pid 708, 206
[hot_view] renders, counter 0→204, stable=host-owned-state preserved, no panic
(gpui-run-int2-20261116162859.*). The same executable launched from the SSH/session-0 context
panicked before render with Creating DirectX renderer → Creating DirectX resources →
0x887A0022 (DXGI_ERROR_NOT_CURRENTLY_AVAILABLE), as did a dx serve --hot-patch run from that
context after a 199.20 s build (gpui-win1-20261116155242.*, gpui-hot-20261116163202.*). So the
earlier launch failure is a non-interactive-session/GPU-availability condition, not a GPUI+
subsecond incompatibility. A dx serve --hot-patch run then executed in the interactive session
itself (scheduled task, SESSION=1, clean target-gpui-hot3): build 473.85 s, app rendered
([hot_view] ... label=v0, counter 0→43), and the first patch applied
(Hot-patching: src\main.rs took 1453ms, [patch_applied] t_ms=5760) — after which the process
died with thread 'main' has overflowed its stack and exit code: 0xc000041d, before rendering
label=v1 (gpui-hot3-20261116-170828.*, gpui-hot3-current.result.txt). GPUI hot-patching on
Windows is blocked for element-returning functions, and works for a framework-free boundary. The
investigation on the same guest (2026-11-16) established:
| Observation | Evidence |
|---|---|
| Patch transport is sound | apply_patch on Windows is LoadLibrary + a jump table (endereço_antigo → endereço_novo), no in-memory detour; runtime dump showed entries=746, aslr_ref=0xcab0/new_base=0xcb10 (RVAs) and resolved targets ~19.2 GB away, and the exe exports main at RVA 0xcab0 as the ASLR anchor. |
| Stack budget is not the cause | the crash reproduced at the default 1 MiB main-thread stack and with /STACK:16777216 (PE verified: 1000000 size of stack reserve). |
| Patching an element-returning view crashes | HotFn::current(hot_view) applied (Hot-patching: src\main.rs took 1238ms, [patch_applied] t_ms=5212) then thread 'main' has overflowed its stack / exit code: 0xc000041d, before any patched render. |
| Patching a leaf function works, repeatedly | HotFn::current(hot_add) (fn(u64) -> u64) patched twice in one process: bumped=1050 at counter=50, then bumped=2193 at counter=193, 303 renders after, no crash (Hot-patching ... 1055ms). |
| A framework-free hot boundary reloads UI values | boundary fn view_data() -> ViewData (label, hs, bg: u32, width: f32, extra), host builds the div(): two warm patches (1324 ms, 1084 ms) produced data=v1 (bg=0x65f46, w=600, extra=panel=contrast) and data=v2 (bg=0x7c2d12, w=640, hs=hs2, extra=panel=dark radius=12 icon=rocket), with 120 and 187 renders after each, counter 4→175, stable preserved, no crash, captured in a QMP screenshot of the same window (gpui-hot7-20261116-175144.log, gpui-hot7-current.result.txt, shot 20261116-175532). |
| Patch DLL does not carry the framework | the Windows patch DLL is 89,600 bytes, exports only main (RVA 0xcb10) and imports only KERNEL32/VCRUNTIME140/UCRT (37 functions); the Linux patch .so carried GPUI (429 MB). |
Consequence recorded for the mechanism contract: on Windows/MSVC with dx/subsecond 0.7.10, hot
boundaries must return framework-free data; code that constructs GPUI elements cannot be the patched
unit. HotFn::try_call also bypasses the jump table entirely when debug_assertions is off, so hot
reload requires a dev-profile build. Full view-code hot reload on Windows remains open (candidate
levers: dx --force-fat-binary, a full-relink patch unit, or a non-Windows patch transport).
First library surface (2026-11-16): auro::hot behind the off-by-default hot-reload feature —
hot() / hot_with() over subsecond::HotFn with AURO_HOT_RELOAD=1 installing the dev-host hook.
No CLI mode, snapshot/restore, or change classification yet.
auro dev hot-reload flow: watch, build, apply reload or fallback, and user-visible reporting.auro-update, Phase 2). This spec covers the dev
loop only.| Path | Observed | Notes |
|---|---|---|
Phase 0 relaunch (auro dev) | ~60 s save-to-visible | Development machine, single visible change, relink dominates; watcher reacts once per edit (spec 0001 status, 2026-11-15). Not a hot reload. |
Slice 0 spike: realistic GPUI-view cdylib warm rebuild | 2m50s cargo / ~171 s wall | Debug, trivial view string change, 429 MB cdylib, GPUI 0.2.2, Linux x86_64; lock contention noted, relink-dominated. Rejects cdylib-view-swap as a latency path. |
Targets below are targets until measured by the method in D6.
auro dev in hot-reload mode runs a host process that owns the GPUI Application, windows,
event loop, Auro runtime, managed host state, and the snapshot store for the lifetime of the dev
session. UI code changes that are classified as reloadable must become visible without closing the
window and without losing opted-in state, by applying updated code/state in the same process and
same GPUI/App/type universe.
The concrete reload mechanism is not yet selected for product integration. It must satisfy the observable contract in this spec (D3, D4, D6, D7) and be proven by prototype/measurement and integrated safely before being declared supported.
Rejected by Slice 0: compiling UI as a separately loaded/unloaded cdylib and swapping it via
libloading for GPUI view/render code. This is infeasible with GPUI 0.2.2 under standard builds due
to generic/type-bound root mounting, AnyView/entity/TypeId/arena dependence on a single GPUI
instance and host App, upstream GPUI being rlib-only, and prohibitive relink cost for a realistic
view library. It must not be reintroduced for GPUI view code without new evidence resolving mount,
type/instance identity, unload safety, and measured performance.
Evidenced candidate (Option 1 consolidation, 2026-11-16, prototype, not integrated):
same-process function-level hot-patching of the tip crate via subsecond 0.7.10 +
dioxus-devtools 0.7.10 driven by dx 0.7.10 (jump-table/ThinLink), with explicit stable
HotFn::current(...) boundaries in reloadable view code and host-owned GPUI
application/window/entities/managed state. On Linux x86_64/Wayland (gpui = "=0.2.2", rustc/cargo
1.99.1, debug debug = 0, warm minimal app), observed save-to-first-new-render was ~271-450 ms
with host state preserved (s1: median 371.5 ms, N=10; s6: median 346 ms, N=20, 20/20 stable), and
core contract properties were demonstrated in prototype scenarios (patch visibility, host-state
preservation, build/syntax-error recovery keeping previous UI, patch-generation failure keeping app
alive on previous code). Documented constraints: patchable code limited to tip-crate hot
boundaries (outside-boundary/init-captured work not retroactive), tip-crate statics/reset on
patch, thread_local! in patched path can fail patch generation, and tooling/layout/snapshot/
classification/integration and representative Auro-scaffold D6 measurement remain pending.
A Windows 11 x86_64 plain (non-GPUI) prototype follow-up (2026-11-16, WinBoat guest, same dx/subsecond
tip-crate mechanism) additionally showed 3/3 warm HotFn patches in 484/504/499 ms with monotonic
counter continuity in the same process (build 30.66 s, clean target/external logs), and a second
plain prototype showed warm view edits applying in 590/523 ms with host state continuous while an
init-captured backend interval change stayed non-retroactive until restart. GPUI 0.2.2 built and
rendered on the same guest in the interactive console session (206 renders, host state preserved),
while dx serve started from the SSH/session-0 context hit DirectX 0x887A0022 before render. On
Windows, patching an element-returning view applies and then overflows the main thread's stack
(0xc000041d, reproduced at 1 MiB and 16 MiB), while a leaf HotFn patched twice with continuity
(bumped=1050/2193) and a framework-free ViewData boundary hot-reloaded UI values twice
(1324/1084 ms, data=v1→data=v2, state preserved, screenshot). auro dev integration remains
unproven.
Rejected: recompiling and relinking the whole app process on every save as the hot path. Rejected: claiming a process restart is hot reload (forbidden by ADR 0008). Rejected: discarding the window on every successful reload.
Hot mode integrated (2026-11-18, experimental, opt-in). [dev] hot = true makes auro dev run
dx serve --hot-patch --interactive false --platform desktop --features hot-reload with
AURO_HOT_RELOAD=1 and AURO_DEV_TRACE=1; scaffolded apps expose a data-only boundary
(view_data() -> HotData wrapped by auro::hot::hot_frame/rendered) and define the
desktop-dev profile the devserver builds (debug=0, incremental=false). auro dev refuses to start unless dx is
0.7.x-compatible and the app declares the hot-reload feature; auro doctor reports the same
inputs.
The 2026-11-16 integration applied patches but did not show them, on Linux as well: GPUI kept the
frame it had already drawn, so the patched boundary only ran on the next interaction. That is the
same failure previously seen on Windows ("patch applied, boundary never observed"). auro::hot
now bumps a revision in the subsecond handler, prints auro:trace hot_patch <n>, and App::try_run
polls it on the main thread every 16 ms and notifies each open root view, so the next frame runs the
patched boundary. The first accepted boundary call after a patch prints
auro:trace hot_render <n>, which gives the dev loop an observable "new UI produced" event instead
of trusting the devserver's "Hot-patching" line. A boundary whose data is rejected by the view
prints auro:trace hot_data_rejected <reason> instead, so the dev loop does not count it as a
reload.
The reloadable unit is the boundary's returned value. Element/layout code in Render is host-stable
and is not reached through the jump table, so editing it does not change the running UI (and does not
crash on Windows); the scaffold prints the boundary value per revision to make that visible. This is
the D2 boundary, not full source-level view reload.
The loop also owns the session lifecycle: the app's pid distinguishes the first launch from a
devserver relaunch (a state report is labelled restarted (...) only after a pid change), a failed
build prints build failed, previous UI still running and applies nothing, a graceful window close
ends the loop with exit 0, and Ctrl-C ends both the devserver and the app process (killing only dx
orphaned the app, observed before the fix).
Linux measurement (niri/Wayland, x86_64, 12 CPUs, rustc 1.99.1, gpui 0.2.2, dx/subsecond/
dioxus-devtools 0.7.10, demo scaffold, warm dependency cache): boundary-only edits measured
473/488/519/521/521/522/528/539/548/567/572 ms save-to-render (N=11, median 521, min 473, max
572) with patch-to-render 8-24 ms; the process id and a ticking host counter continued across
patches (52→59). With incremental=true the same app measured median 650.5 ms (N=10, 547-1722); a
debug=2 profile measured 3.3 s. The demo window was visually confirmed showing the patched
title/accent. The target is < 500 ms: 3/11 edits landed under it and the median did not.
Windows measurement (2026-11-18, WinBoat guest: Windows 11 Pro 10.0.26200.0 x64, rustc/cargo
1.99.0 MSVC, dx/subsecond/dioxus-devtools 0.7.10, interactive console session 1, Defender exclusions
for the work, cargo and rustup directories): the integrated scaffold built (151.59 s warm-target)
and rendered; the first boundary edit produced view data -> Win1 with the patched accent in the
same process (pid 3444) while the host ticker continued (133→134...). First patch after launch:
2806 ms save-to-render (patch_took_ms 2715). Five steady-state patches:
1823/1505/1375/1237/1282 ms (N=5, median 1375), patch-to-render 8-38 ms (one cold patch 360 ms).
A type error kept the previous UI live; the fixing edit reloaded in 1696 ms with the same pid;
closing the window ended the loop with exit 0 and the task exited 0. Windows is slower than Linux
because MSVC compile/link dominates the patch, not the repaint. The data boundary remains the only
reloadable unit, as on Linux.
Windows re-test, four-crate scaffold (2026-11-18, WinBoat guest, simple data boundary): a fresh
auro new app with ui/data/types/bin and a plain ViewData boundary applied nine patches in
873/1872/1735/1229/1168/961/820/2359/921 ms save-to-render (N=9, median 1168, min 820, max
2359; patch_took 686-2196, patch-to-render 3-13 ms) with the same pid, window and state. That is
~15% below the earlier single-crate median (1375 ms) but still above 500 ms. The guarded HotData
template then ran through auro dev in the same guest: 851/765/768/880/813/897/816/752/768 ms
(N=9, median 813, p95 897, min 752, max 897; patch-to-render 2-16 ms), same pid/window, patch DLL
14,848 bytes. Adding Defender exclusions for the app and repo did not change the conclusion: four
steady patches measured 719-735 ms (one 1293 ms outlier). incremental = true measured a 1966 ms
first patch and 830/848/799/819 ms steady (N=4), also no improvement. codegen-units = 1 measured
810/748/769/738/719 ms (N=5, median 748). Responsibility for the remaining Windows gap is in the
MSVC compile/link of the boundary and bin, not the repaint, the incremental session or codegen-unit
count. rust-lld linked a plain cargo build successfully, but dx serve --hot-patch refused
with Missing linker args for fat link of 'auro_hot_template2'. The tip crate likely did not run through linker interception for this build; dx 0.7.10's fat-link interception requires the default
linker, so lld is not a usable lever for the Windows patch path. Adding /OPT:REF and /OPT:ICF
to the MSVC link measured 765/817/848/767 ms save-to-render (N=4, median 767; patch_took
641-727 ms), no improvement over the 748 ms codegen-units series. The host-code restart path was
also exercised on Windows with the latest CLI: a ui/src/lib.rs save stopped dx and the app,
rebuilt in 5.91 s, launched a new pid and restored the snapshot; a following data edit
hot-patched in 910 ms (11 ms patch-to-render).
macOS measurement (2026-11-18, GitHub macOS 26 arm64 runner). There is no local Apple host,
but the manual Hot reload macOS benchmark workflow ran the guarded four-crate scaffold with the
prebuilt dx 0.7.10 on macos-latest (macos-26-arm64): auro dev, six warm-up boundary edits,
then twelve measured edits. Save-to-render was
536/520/444/625/1071/598/481/507/439/512/462/372 ms (N=12, median 509.5, p95 1071, min 372, max 1071;
patch-to-render 2-17 ms), with the app process and window kept. A first cold run without warm-up
measured median 515 ms (N=12, 431-715). A second six-warmup run, with a seeded snapshot and a
host-restart check appended, measured median 837.0 ms (N=12, p95 2096, 583-2096); the restart passed:
outside the hot boundary; restarting, restarted (state restored) and a new app pid. A third run
with twelve warm-up edits measured median 748.5 ms (N=12, p95 1114, 611-1114), so extra warm-up does not fix
the variance. The two six-warmup runs span 509.5-837 ms on the shared runner; that is not stable
enough to claim the target met. No local Apple hardware, hardened-runtime build, signing or
interactive Aqua session was exercised. macOS is measured but not GA, and CI also builds/tests the
feature and the generated scaffold on macos-latest.
Boundary crate split (2026-11-18, integrated). The first integrated scaffold kept the boundary
and the GPUI view in the same bin crate. Every patch then recompiled and relinked the view code and
dx produced a patch library containing GPUI; the measured Linux median was 521 ms and the patch
artifact was the size of the app. The scaffold now generates four workspace crates:
| Crate | Contents | Depends on |
|---|---|---|
types | the decoded ViewData and the fixed HotData frame | nothing |
data | the hot boundary view_data() -> HotData | types |
ui | Render, window code, the element tree, snapshot/autosave | auro, types, serde |
| the bin | main wiring ui::run(data::view_data) | ui, data |
ui deliberately does not depend on data: dx recompiles the changed crate and its dependents,
so editing the boundary recompiles data and the thin bin, not GPUI or the view. The patch library
is ~12 KB instead of the size of the fat binary (the loader keeps each applied library mapped, so
this also bounds long-session growth), apply and load are cheap, and the steady-state
save-to-render distribution on the same Linux reference machine was 325-394 ms (N=12, median 368)
with patch_took 268-325 ms and patch-to-render 1-26 ms; the same setup with a plain struct
boundary and no fixed-frame check measured median 288 ms (N=12). The process id, window and host
state continued across patches. A scaffold test asserts the crate edges (no ui -> data, no
data -> auro) so the fast path cannot be lost by an innocuous dependency addition.
Apply-failure containment (2026-11-18). auro::hot owns the devserver connection instead of
delegating to dioxus_devtools::connect_subsecond, which unwraps a failed apply and kills the
listener. A patch that cannot be loaded (missing sentinel, bad relocation, truncated file, loader
panic) is caught, reported as auro:trace hot_patch_failed <reason> and as
auro: patch rejected by the app: <reason>, and the previous jump table keeps running. The
websocket stays open, so the next edit can still apply. A committed patch wakes the main thread
through a tokio::sync::watch channel rather than a 16 ms poll; the measured patch-to-render
latency dropped to 1-26 ms and an idle app no longer wakes twice a frame.
Code that must survive a reload lives on the host-stable side: process bootstrap, window lifecycle, the tokio runtime, host-owned managed state containers, snapshot persistence, and the reload/apply machinery. Code that defines views and reloadable UI behaviour lives in the reloadable side.
The generated project layout and the auro API must make this boundary explicit once a mechanism is
chosen. A single-crate bin scaffold (Phase 0 shape) is sufficient for relaunch mode but is not known
sufficient for in-process hot reload; hot-reload-capable projects may require a specific layout,
build flags, or patchable/reloadable compilation units. The exact shape is fixed by the
implementation/prototype that proves the mechanism and recorded here when chosen.
State, tasks, subscriptions, and callbacks owned by reloadable code must have an explicit teardown or invalidation contract so replaced code is never invoked after a reload completes or is rolled back.
Rejected: implicit, arbitrary mutation of live memory without a snapshot/restore and teardown/rollback contract. Rejected: storing entity handles or view callbacks in process-global state that cannot be invalidated on reload.
Implemented layout (2026-11-18, ADR 0022).
The boundary is a crate edge, not a convention: ui owns the
host-stable Render/window/element code and must not depend on data; data owns the reloadable
boundary and depends only on types. The bin wires the function pointer
(ui::run(data::view_data)), so a patch replaces code in data without recompiling the view. The
scaffold test checks both edges. types::HotData is the fixed, #[repr(C)] frame exchanged with
the running host; ViewData can change inside it. A schema mismatch is rejected by the host and
reported, and the old values stay on screen instead of being reinterpreted under a new layout.
The host owns the snapshot store. A snapshot is a versioned envelope containing named, typed entries for state that opts into preservation. At minimum the format records:
format_version (snapshot schema version, integer).serde-compatible; the wire encoding is fixed at implementation time and recorded here).State categories:
| Category | Owner | Reload behaviour |
|---|---|---|
| View/UI state explicitly marked restorable | Reloadable UI, via snapshot contract | Serialized before apply/restart fallback, restored after successful apply/start. On decode/version mismatch, reset that entry and report it. |
| Host-managed state outside the replaced/restarted UI unit | Host | Preserved in memory across in-process reload when host-stable; preserved across state-preserving restart only through snapshot/persisted host state. Never passed as a borrowed reference that outlives its owner. |
| Ephemeral/UI-local state not opted in | Reloadable UI | Reset on reload/restart. Reset must be visible in dev diagnostics, not silent. |
| External/non-serialisable resources | OS/runtime | Recreated or dropped according to the resource contract; loss reported. |
A view or state unit opts into preservation by implementing reload snapshot/restore hooks for its stable key. “Stable key” means stable across saves for the same logical UI element within a dev session (window label + root/view identity as defined by the API). Renaming/removing a key is a reset of that entry.
Rejected: snapshotting arbitrary memory or entity graphs implicitly. Rejected: a silent fallback to default state on mismatch.
Implemented (2026-11-16). auro-core::snapshot, re-exported as
auro::{Snapshot, ReloadSnapshot, Restored, ResetReason}, fixes the envelope: JSON with
format_version (currently 1), the build identity of the writer, and a map of stable key to
{ "version": u32, "payload": <serde JSON> }. State opts in by implementing ReloadSnapshot with
its KEY and VERSION. Snapshot::restore consumes one entry; a missing key, a version mismatch or
an undecodable payload drops only that entry and returns Restored::Reset(reason) whose
message() is printable — nothing defaults silently. A format_version this build does not
understand makes Snapshot::decode fail outright. Snapshot::save_to writes atomically (sibling
temporary file plus rename) and load_from separates "missing" (None) from "unreadable" (error),
so a corrupted file never looks like fresh state. auro_core::Autosave captures watched entries on
the thread that calls tick() (UI state stays on the main thread; no background reader), writes
after a 250 ms quiet period, and exposes flush() for an explicit save; the dev path is
<platform data dir>/<identifier>/dev-snapshot.json; a leading UTF-8 BOM is tolerated on load. The
scaffold wires it: CounterState
implements ReloadSnapshot, the view restores on start and prints auro: state restored from <path>
or auro: state reset: <reason>, and a click marks dirty then ticks 350 ms later. Verified on
niri/Wayland 2026-11-16: a hand-written snapshot with count: 7 restored (state restored), and the
same entry with version: 2 produced state reset: snapshot entry version 2 cannot be read by version 1; state starts from its default; both runs opened the window and exited 0, and the file was
left untouched because no click happened. Not yet wired to capture/restore around a reload or a
state-preserving restart.
| Outcome | Condition | Host behaviour | User-visible label |
|---|---|---|---|
| Hot-reloaded | Reloadable build/patch succeeds, compatibility checks pass, apply and restore complete (with or without per-entry resets) | Keep window and host state; present updated UI; repaint | “reloaded” with duration and any reset warnings |
| Build failed | A boundary build/patch compilation fails | Keep previous UI active and interactive; do not apply a partial reload | compiler/build diagnostics; “previous UI still running” |
| Host restart, rebuild failed | A host-code save restarted the devserver and its rebuild fails | Keep the previous app running; keep the devserver for the next save; do not apply a partial reload | “host rebuild failed; previous UI still running” |
| Reload failed, recovered | Build/patch succeeds but compatibility/apply/restore fails and previous UI remains valid or can be safely rolled back | Keep or restore previous UI as applicable; do not present as reloaded | explicit failure reason |
| State-preserving restart (fallback) | Reload cannot be completed safely, or a configured/required restart change occurred | Restart app/host session; restore the last snapshot the app wrote to its host-controlled store. State changed since that write is reset and reported. | “restarted (state restored)” or “restarted (state reset: <reason>)” - never “hot reloaded” |
| Hard failure | Restart/restore impossible | Exit non-zero with diagnostic | error |
A failed build must never apply broken code. A boundary build failure keeps the previous UI active. A host-code save restarts the devserver while keeping the previous app visible; a failed host rebuild therefore keeps that app running, is reported, and the next successful save starts a new app before the old one is retired. Reloadable tasks/callbacks that can outlive a reload must be cancellable or invalidated before replaced code can run; the host must not invoke replaced code after a failed or completed reload.
Rejected: applying partial/broken reloads. Rejected: leaving tasks running against replaced code. Rejected: presenting a restart as hot reload.
Implemented (2026-11-16, relaunch mode). The dev loop reads the app's snapshot report from its
stderr and prints the label for the relaunch that follows a save: auro: restarted (state restored)
or auro: restarted (state reset: <reason>). The first launch prints no label because nothing
restarted. A failed boundary rebuild prints the tail of the compiler output and keeps the previous
UI running. A failed host rebuild is reported as host rebuild failed; previous UI still running;
the old app stays visible until the replacement launches.
On Windows the app runs from target/auro-dev/<stem>-<pid>-<n>.exe: a running image cannot be
relinked, and a staging failure is reported while the previous UI stays up. Verified on niri/Wayland
and on Windows 11 (WinBoat), both with a hand-written snapshot: restore and version-mismatch reset
each produced the matching label, initial start produced none, and the two relaunches were traced at
2408/2357/2380 ms (Linux) and 10754/8159 ms (Windows) save-to-build, debug, warm dependency cache.
Implemented (2026-11-18, hot mode). auro dev labels the hot outcomes separately: an applied
patch prints hot patch applied (<took> ms, <elapsed> ms after the save) and, when the boundary
renders, reloaded in <n> ms (window kept) plus the JSON trace; a failed boundary build prints
build failed, previous UI still running and applies nothing; Failed to hot-patch app prints
hot patch failed, dev server is rebuilding the app. A host-code save prints outside the hot boundary; restarting the app (state preserved) and a failed host rebuild prints host rebuild failed; previous UI still running. A relaunch is detected by a changed app
pid (auro:trace pid) and only then is the snapshot report labelled restarted (state restored) or
restarted (state reset: <reason>); the first launch is not labelled. A graceful app exit ends the
loop with exit 0, and Ctrl-C kills the devserver and the app process (verified on Linux; the Windows
run was ended by closing its window, which also exited 0). The < 500 ms target is met by the Linux
median (368 ms) for the documented warm case; Windows exceeds it and macOS is above it on a shared
CI runner (see D6). The label never claims a target it did not measure.
Rejected patches (2026-11-18). A patch the app cannot load prints
auro: patch rejected by the app: <reason>; the previous UI stays live and no timing line is
emitted. A frame the view refuses (schema or bounds check) prints
auro: reload rejected by the view: <reason>; previous UI kept and is never presented as a
successful reload; the view reports that frame as rejected rather than rendered
(hot_frame/rendered), so no hot_render or timing line is produced. Observed on Linux: a
SCHEMA bump produced hot_data_rejected and left the previous values, no reload line; reverting
SCHEMA then applied in 959 ms in the same process, so the listener and jump table survived the
rejection. A patched boundary that panics is caught by the generated view, reported as
hot data rejected: the patched boundary panicked, and leaves the previous values and process
alive; removing the panic applied in 327 ms in the same process.
Host-code fallback (2026-11-18). A save in ui/src/lib.rs was classified outside the hot
boundary, the devserver and app were restarted (build 3.14 s), the app printed state restored from
the existing snapshot, and the dev loop printed restarted (state restored); the new process
rendered the edited button and a following data edit hot-patched in 978 ms with a 5 ms
patch-to-render. Editor swap files beside the source produced no restart. A host rebuild with a
syntax error kept the previous app alive (same pid) and printed auro: host rebuild failed; previous UI still running; the fixed save rebuilt in 3.15 s, launched a new pid and restored the
snapshot. The same host restart succeeded on Windows: a ui/src/lib.rs save rebuilt in 5.91 s,
launched a new pid, restored the snapshot and the next data edit patched in 910 ms. A Windows
host rebuild with a syntax error kept the previous app (pid 11740) and printed host rebuild failed; previous UI still running. macOS CI also passed the restart check (restarted (state restored),
new pid) after a seeded snapshot. The old app remains interactive during the build; state changed
there after the replacement has loaded its snapshot is not guaranteed to carry over. This is the
state-preserving restart path required by D4/D7, not a reload.
The dev host and reloadable UI are built under a compatible toolchain/profile/target/dependency set for the selected reload mechanism. Before apply, the host checks a build identity and any mechanism-specific compatibility data required to avoid undefined behaviour; a mismatch is a reload failure (D4), not a best-effort apply.
If the chosen mechanism involves dynamically loaded artifacts, teardown/quiesce and unload safety are required; leaked unloads or live references into unloaded code are treated as reload failure with safe fallback. If the chosen mechanism patches in-process code, patch applicability/rollback safety must be explicit and diagnosable.
Rejected: promising stable cross-version reload compatibility in 0.x. Rejected: silent best-effort apply on mismatch.
Implemented guard (2026-11-18). The generated boundary returns types::HotData, a fixed
#[repr(C)] frame (240 data bytes) with a schema number, title length and accent. The running host
checks the schema and bounds before decoding any field, so a patch compiled against a changed
ViewData cannot make the old host read a different layout. types documents the rule: change
ViewData and its encoder, bump HotData::SCHEMA; do not change HotData's shape. The raw typed
auro::hot::hot boundary remains available for advanced cases and carries the documented layout
agreement; the scaffold uses the guarded frame.
“Save-to-visible” is defined as: wall-clock time from the editor save event observed by the watcher to the first frame presenting the updated UI (or, when pixels cannot be observed headlessly, to the host’s “reload committed and repaint requested” event - the method must be stated with the measurement). Each recorded measurement states:
save_to_patch), dx's reported patch work (patch_took,
compile+link+load as dx reports it), and apply→first render (patch_to_render). dx 0.7.10 does
not expose compile, link and loader-load separately; that finer split remains open.The host must emit machine-readable timing events in dev mode (log/trace or structured output)
sufficient to compute this metric without manual stopwatch use. AURO_DEV_TRACE may be extended for
this purpose. Numbers published in docs, roadmap, or performance budget are measured or explicitly
marked as targets.
Implemented (2026-11-16, relaunch mode). auro dev sets AURO_DEV_TRACE for the child; the app
then prints auro:trace window_requested <label> immediately after open_window, and the dev loop
prints one line per save:
{"event":"relaunch","window":"main","save_to_build_ms":N,"build_to_window_ms":N,"save_to_window_ms":N}
saved_at is the first watcher event of a burst (not the editor's own save timestamp), built_at is
the moment the replacement binary exists, and the window marker means the first repaint was
requested - the method is "repaint requested", not measured pixels. The loop polls the watcher at
50 ms, which bounds the resolution of build_to_window_ms.
Measured run (2026-11-16, niri/Wayland, x86_64, debug, warm dependency cache, scaffold demo,
three consecutive and visible reloads): save_to_build_ms 2408/2357/2380, build_to_window_ms
400/350/350, save_to_window_ms 2809/2708/2730 (medians 2380 / 350 / 2730); closing the window
through auro dev exited 0. This is relaunch mode, not hot reload, and it is far below the earlier
~60 s figure recorded for a different configuration; both numbers stay labelled with their method.
Implemented (2026-11-18, hot mode). The dev loop sets AURO_DEV_TRACE=1 for dx; the app prints
auro:trace pid <pid>, the patch handler prints auro:trace hot_patch <n>, and the first hot
boundary render after a patch prints auro:trace hot_render <n>. Each edit produces one line:
{"event":"hot_reload","save_to_patch_ms":N,"patch_to_render_ms":N,"save_to_render_ms":N,"patch_took_ms":N}
save_to_patch_ms is the dev loop's own watcher timestamp to the devserver's patch line (or the
handler marker when the line is missing); patch_to_render_ms ends at the marker printed inside the
boundary call, i.e. the render that produces the new frame, not a measured pixel. The main thread
polls the patch revision every 16 ms, and the loop polls its channels every 50 ms; those bound the
resolution. patch_took_ms is dx's own report and is not used for the target.
Measured run (2026-11-18, niri/Wayland, x86_64, 12 CPUs, rustc 1.99.1, gpui 0.2.2,
dx/subsecond/dioxus-devtools 0.7.10, scaffold demo, desktop-dev debug=0, incremental=false,
warm dependency cache, boundary-only edits): save_to_render_ms
473/488/519/521/521/522/528/539/548/567/572 (N=11, median 521, min 473, max 572);
patch_to_render_ms 8-24; patch_took_ms 491-575. The same app with incremental=true measured
median 650.5 ms (N=10, range 547-1722). An earlier debug=2 profile measured 3.3 s. Host state
continued across patches in the same process (pid unchanged, counter 52→59), and a deliberate type
error kept the previous UI live until the fixing edit reloaded in 634 ms. A fresh auro new scaffold
of the template reloaded its boundary in 580 ms (revision 1, same pid), which verifies the generated
manifest/profile as well as the demo fixture. Windows numbers are in D1/platform notes; macOS is
unmeasured, so the target stays a target.
Measured run (2026-11-18, four-crate scaffold, niri/Wayland, x86_64, 12 CPUs, rustc 1.99.1,
gpui 0.2.2, dx/subsecond/dioxus-devtools 0.7.10, desktop-dev debug=0, incremental=false,
warm dependency cache, boundary edits in data/src/lib.rs): save_to_render_ms
393/371/385/370/366/339/357/370/394/350/325/366 (N=12, median 368, p95 394, min 325, max 394);
patch_to_render_ms 1-26; patch_took_ms 268-325. The same layout with a plain struct boundary
(no fixed-frame guard) measured 306/271/292/252/270/247/313/264/387/357/309/283 (N=12, median
287.5, min 247, max 387), isolating ~80 ms for the guarded frame. Both series ran while an
unrelated workspace test build kept the host at load average ~16; the numbers are therefore
conservative for this machine. The first patch after launch can be slower (1698 ms on the guarded
scaffold) because dx compiles the changed boundary crate and its tip for the first time; the
target case is a warm edit, and the first patch is reported separately in the raw log. The same pid,
window and host state continued across all patches. A type error kept the previous UI live and the
fix applied in 270 ms (simple frame). A types::HotData::SCHEMA change applied as a patch was
rejected by the running view (hot data rejected: ... different view-data schema), left the
previous values on screen and did not crash.
Measured run (2026-11-18, macOS 26 arm64 GitHub runner, guarded four-crate scaffold): the
manual Hot reload macOS benchmark workflow installed the prebuilt dx 0.7.10, ran auro dev
with AURO_HOT_RELOAD=1/AURO_DEV_TRACE=1, applied six warm-up edits, then twelve measured edits
to data/src/lib.rs. save_to_render_ms was
536/520/444/625/1071/598/481/507/439/512/462/372 (N=12, median 509.5, min 372, max 1071);
patch_to_render_ms 2-17; the app process and window stayed. The first cold run without warm-up
measured 715/699/517/513/467/655/571/439/445/698/508/431 (N=12, median 515, min 431, max 715).
macos-26-arm64 is a shared GitHub runner, so the spread and the 1071 ms outlier are environment
noise, not a controlled hardware benchmark; no local Apple hardware, signing or hardened-runtime
build was exercised. Five of the twelve warm edits were under 500 ms, so macOS is recorded as at
the target boundary, not as met.
Target (from ADR 0008 / roadmap): < 500 ms save-to-visible for a view-only change on a warm
incremental build, with state preserved. This is a target, not a guarantee, until recorded under D6.
The integrated scaffold uses a warm dependency cache and a one-file ThinLink rebuild with
incremental=false; that is the measured method, and the target wording predates it.
Rejected: unverifiable latency claims. Rejected: counting only compile time while excluding apply/restore/repaint.
Not every edit is safely reloadable in-process. The dev loop classifies changes:
| Change class | Expected path | Notes |
|---|---|---|
| Reloadable UI/view code and resources within the supported reload unit | Hot-reload | Primary path; must preserve opted-in state per D3. |
| Host-stable/bootstrap code, host dependency graph, toolchain/config affecting host/runtime compatibility | State-preserving restart or full restart | Classified and reported; never a silent no-op. |
Auro.toml / window-identity changes | Reload config in host where safe; otherwise restart with explanation | Must not corrupt running host assumptions. |
| Compatibility/build identity mismatch after rebuild | Reload failed → fallback per D4/D5 |
The classification rules are part of the implementation contract and must be documented for app authors once implemented.
Hot mode rules (2026-11-18, implemented): only code reached through auro::hot::hot/
hot_with reloads in-process. In the generated four-crate layout the reloadable unit is
data/src/lib.rs; ui (the Render impl, layout, element construction) is outside the jump table
and is deliberately not a dependency of data. Editing ui, types, the bin, a dependency or the
dev profile is host code: a patch cannot replace the running view's code. A save outside
data/src is labelled at save time (auro: change in ui/src/lib.rs is outside the hot boundary; restarting the app (state preserved)), the devserver and app are restarted, the snapshot is
restored, and the outcome is labelled restarted (state restored) or
restarted (state reset: <reason>), never reloaded. Editor swap/lock files are ignored. The
types::HotData schema check still rejects a frame built against a changed data layout if a patch
races the restart. A change to a non-tip crate or the dev profile takes the same restart path.
A patch that cannot be generated makes dx start a full rebuild; the dev loop prints
hot patch failed, dev server is rebuilding the app. A build error in a boundary patch keeps the
previous UI live. A host-code change keeps the previous app visible while the replacement builds;
a failed host rebuild leaves that UI running and the dev loop reports
host rebuild failed; previous UI still running.
Staged delivery (aligns roadmap):
auro dev for supported project layouts and
mechanisms; view-only reloads; snapshot/restore for opted-in view state; visible diagnostics and
timing; fallback to state-preserving restart where reload is not possible. Correctness and honesty
over coverage.Rejected: enabling an unsafe/undefined reload path by default. Rejected: declaring GA without measured D6 evidence for the documented case.
This section fixes the surfaces this spec introduces or constrains. Signatures shown as
rust,ignore are illustrative until implemented; normative details are the behavioural contracts
above and the keys/items listed here.
auro-cli)| Surface | Behaviour |
|---|---|
auro dev | Default remains the documented relaunch loop until hot reload is declared stable for the selected project; hot reload is enabled by an explicit opt-in (flag and/or [dev] config key defined at implementation time and recorded in spec 0002/CLI docs). |
auro dev (hot-reload mode) | Starts/uses the dev host, watches configured paths, builds the reload unit(s), performs reload or fallback per D4, streams diagnostics, and emits timing events per D6. |
| Exit/status | Ctrl-C stops host and child tasks cleanly (exit 0). Natural app exit in dev follows current contract. A failed boundary build keeps the session alive with previous UI; a failed host rebuild keeps the previous app and the devserver alive and reports it. A non-recoverable host/reload failure exits non-zero with a labelled reason. |
| Diagnostics | Build failures, compatibility mismatches, apply/restore failures, snapshot resets, and fallbacks are reported with actionable labels distinguishing “reloaded”, “previous UI still running”, and “restarted (state restored/reset)”. |
Auro.toml, coordinated with spec 0002)Additions required by this spec (exact key names finalised at implementation; defaults must preserve current relaunch behaviour until GA):
Any new key is added to spec 0002, validation, and auro doctor in the same change that implements
it.
auro, auro-core, auro-ui, auro-ipc)Illustrative (non-normative):
pub trait ReloadSnapshot: serde::Serialize + serde::de::DeserializeOwned {
const SNAPSHOT_KEY: &'static str;
const SNAPSHOT_VERSION: u32;
}
The implementation must define and record a mechanism-specific contract covering, at minimum:
A separately loaded/unloaded cdylib C-ABI contract for GPUI view code is not part of this spec
after the Slice 0 rejection unless new evidence overturns that conclusion.
auro new must continue to scaffold a project that builds and runs under the default (relaunch) dev
loop. When hot reload mode is enabled for a project, the project must satisfy the documented layout
and build/mechanism requirements; auro doctor reports whether the current project is hot-reload
capable and why not. Migration/upgrade steps for existing Phase 0 scaffolds are documented in the
implementing change.
Migration (2026-11-18). An existing single-crate app becomes hot-reload capable in this shape:
ui (view, Render, element tree, snapshot/autosave;
depends on auro and types, never on data), data (the boundary; depends only on types),
and types (ViewData plus the fixed HotData frame). The generated app is the reference:
cargo new a scaffold and copy the manifests. ui must not depend on data; that edge is what
keeps GPUI out of the patch.data::view_data() -> HotData and call ui::run(data::view_data)
from main. The view decodes the frame; the boundary never constructs GPUI types.[features] hot-reload = ["<app>-ui/hot-reload"] (the ui crate forwards to
auro/hot-reload), the [profile.desktop-dev] block (inherits = "dev", debug = 0,
incremental = false), and a Dioxus.toml with default_platform = "desktop".[dev] hot = true and include src, ui/src, data/src, types/src and Auro.toml in
[dev] watch. auro doctor prints which of the manifest feature, dx, and the config flag is
missing.A single-crate app can still run the relaunch loop unchanged; hot mode only claims the supported layout.
Checks are runnable by someone who did not write the implementation. Items that require a real display or platform-specific behaviour are marked; headless/CI-safe subsets are preferred where possible. Acceptance 1-5 define the contract; the status paragraph after the list records what the integrated opt-in path demonstrates and what remains. Prototype evidence (Option 1 consolidation, 2026-11-16, not integrated) demonstrated analogous properties in minimal GPUI 0.2.2 scenarios (host-state preservation across patches, build/syntax failure keeping previous UI alive, patch-generation failure keeping app on previous code, and warm view-only save-to-first-new-render ~271-450 ms, s1/s6) before the feature was integrated.
auro dev on a hot-reload-capable demo
project performs a view-only reload without closing the window; Ctrl-C and natural window-close
semantics remain correct (spec 0001 acceptance 3/4). Platform limitations are recorded, not hidden.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass. CI also runs the
hot-reload feature tests and builds/tests a generated scaffold on Linux, macOS and Windows, so
template drift is caught on the platforms without a live hot-reload measurement. Spec 0001 open
question, roadmap, performance budget, changelog, and architecture notes are updated to refer to
this spec and the measured status.Status (2026-11-18, integrated hot mode, four-crate scaffold): item 2 (a boundary build failure
keeps the previous UI) is demonstrated on Linux and Windows; a failed host rebuild is reported
separately and leaves the previous app running until the next successful save. Item 3's apply-failure path is contained by
apply_patch error/panic handling (unit-tested selection, manual rejection of an incompatible frame
observed). Item 5 is demonstrated: a save outside data/src restarts the devserver and app,
restores the snapshot and is labelled restarted (state restored). Item 6 is demonstrated
on Linux (N=12, median 368 ms, p95 394, min 325, max 394, patch-to-render 1-26 ms), Windows (N=9, median
813 ms, p95 897, 752-897, patch-to-render 2-16 ms) and macOS (two runs, N=12 after warm-up, medians 509.5, 837.0 and
956.0 ms, p95 1071/2096/1563, 372-2096,
patch-to-render 2-17 ms), each recorded with machine and method in D6. Item 7 is partially
demonstrated (same window, pid and host state across patches on Linux, Windows and macOS; host
restart with state restored on Linux, Windows and macOS CI; graceful exit and Ctrl-C cleanup on
Linux and Windows) for boundary-only edits. Item 1 has a headless
fixture for mounting the view, changing the boundary output and keeping state
(crates/auro/tests/hot_fixture.rs); it does not load a patch dylib, and the snapshot roundtrip is
covered by the auro-core tests. Item 4 rests on the crate boundary (ui does not depend on data, only
hot-wrapped calls read the jump table); item 8 is the repository gates. The Linux median is now
under 500 ms for the documented warm case, macOS is above the target on a shared CI runner and
Windows remains above it, so the target is not met platform-wide and experimental mode must not
claim it.
GA additionally requires: measured < 500 ms save-to-visible for the documented warm view-only case on each Tier 1 platform (or an explicit, approved revision of the target recorded in the performance budget), published numbers, and a stable documented author contract for reloadable state.
| Question | Where it settles |
|---|---|
| Reload mechanism: in-process/function-level patching feasibility (e.g. subsecond-style) on Linux x86_64 with GPUI 0.2.2, and alternatives if not viable | Partially evidenced (prototype, 2026-11-16): subsecond/dx tip-crate HotFn patching viable in minimal GPUI 0.2.2 cases with constraints; on Windows 11 x86_64 a plain (non-GPUI) prototype applied 3/3 warm patches (484/504/499 ms) with state continuity and a second plain prototype showed view edits at 590/523 ms with host state continuous and an init-captured backend change applying only after restart; GPUI 0.2.2 built and rendered on Windows in the interactive console session; there, a patch of an element-returning view applies then overflows the main thread's stack, while a leaf HotFn and a framework-free ViewData boundary hot-patched repeatedly with state preserved (UI values reloaded in 1324/1084 ms). Productization, representative D6, and other platforms remain open. Mechanism recorded here; ADR revision/addition only if decision changes. |
| Exact scaffold/layout/build flags for hot-reload-capable projects and migration from Phase 0 layout | Implementation of this spec; recorded here when chosen |
| Canonical snapshot encoding (JSON, CBOR, postcard/bincode-class) and compatibility policy | Implementation; must remain serde-compatible at the API boundary |
How managed State<T> participates when its type is defined in reloadable code vs host-stable code | Implementation + follow-up ADR/spec if it changes state ownership rules (D5 of spec 0001) |
| Debug/release mixing, optimization levels, and symbol/debug info required by the chosen mechanism | Implementation, per platform notes |
| In-app surfacing of build/reload diagnostics (overlay/panel) vs terminal-only in experimental mode | auro-ui/dev UX follow-up; terminal reporting is the minimum |
| Windows and macOS feasibility, code-signing implications, and debugger behavior for the chosen mechanism | Partially evidenced on Windows x86_64 (2026-11-16, WinBoat guest): plain non-GPUI tip-crate HotFn patching applied 3/3 warm patches with continuity; a second plain prototype showed frontend view edits (590/523 ms) with host state continuous and an init-captured backend interval applying only after restart; GPUI 0.2.2 built and rendered in the interactive console session, but dx serve from session 0 hit DirectX 0x887A0022 before render, and patching an element-returning view in session 1 applied then overflowed the main thread's stack (0xc000041d); a leaf HotFn and a framework-free ViewData boundary hot-patched repeatedly with state preserved, so Windows hot reload is limited to framework-free boundaries. macOS, signing/entitlements, debugger behavior, and representative D6 remain unverified. Integrated re-test (2026-11-18): the Windows scaffold applied boundary patches in the interactive session with the same pid and continuing state (median 1375 ms save-to-render, N=5 steady; see D1), kept the previous UI on a type error and exited 0 when the window closed. macOS measurement (2026-11-18): a manual GitHub macos-26-arm64 workflow measured medians 509.5 and 837.0 ms on two six-warmup runs (N=12 each, 372-2096); a host restart with snapshot restore passed; local hardware and hardened-runtime signing remain open. |
Change classification for types/ui/bin edits in hot mode: dx still compiles a patch, the running host keeps its old code, and the schema guard rejects an incompatible data frame; a restart is the honest path | Implemented (2026-11-18): the dev loop classifies .rs/.toml saves, restarts the devserver and app for host-code changes, restores the snapshot, labels `restarted (state restored |
Status: Implemented (2026-11-17)
ADR 0009 fixes the product decision: Auro is the application layer and ships no component toolkit. This spec defines the small seam that makes the decision usable: how an app initializes the toolkit it chose and how it puts that toolkit's root around Auro's view.
App::setup: a hook that runs after GPUI starts and before any window opens.App::root_with: a way for the app to build the window's root view instead of V::default().App::root stays as the Default-only sugar.app.windows[].theme to its toolkit.gpui-component 0.5.x with GPUI 0.2.2).auro-ui remains the GPUI seam: re-exports, tokens, and the primitives the scaffold needs. A
toolkit is an app dependency (gpui-component, a private crate, or none). See
ADR 0009.
App::setup registers a closure invoked once per app, in registration order, after the GPUI
application starts and before any configured window opens. It receives the parsed Config so the
app can choose a toolkit theme from the same file that declares the windows.
Setup APIs have no error channel. A panic in setup is an application bug and aborts the process the same way a panic in a view would; Auro does not hide it.
App::root_with takes a builder that returns Entity<V> for the window. It exists because some
toolkits must be the window root (they host dialogs, notifications, sheets and input focus above
the app's view). The builder runs inside the GPUI window callback, after the window is created and
its title is set.
App::root::<V> is sugar for a builder that returns cx.new(|_| V::default()). Both paths share
the same window creation and title handling; a change to one applies to the other.
Every window declared in Auro.toml is opened once, in declaration order, using the root
registered for its label. A window with no matching root logs an error and does not open. Labels
remain unique. Setup does not change the window list.
The app receives the same Config that declares its windows. app.windows[].theme is parsed and
passed through; the app maps it to its toolkit in setup. auro doctor reports a non-system theme
as toolkit-owned instead of claiming the renderer ignores it.
Per-window themes depend on the toolkit. A toolkit with one global theme (as gpui-component has)
can honor one window's theme, not a different theme per window; the app must decide and document
that. Auro does not pretend otherwise.
The documented integration is gpui-component 0.5.x with the pinned gpui = 0.2.2. The current
component line (0.10.x) requires gpui-pre = 0.3.12; using it requires moving the renderer pin and
is not part of this spec. Measured probe (2026-11-17, Linux x86_64, release, stripped,
panic = "abort", one Button + Root): 22.0 MB with the toolkit against 15.5 MB without it, and
spawn→window 147.3 ms against 139.8 ms (median, N=5; not first paint). The app pays the toolkit's
binary size; Auro's minimal app does not.
impl App {
/// Runs after GPUI starts and before any window opens; registration order.
pub fn setup(self, f: impl Fn(&mut gpui::App, &Config) + 'static) -> Self;
/// Builds the window root instead of `V::default()`.
pub fn root_with<V: Render + 'static>(
self,
label: &'static str,
f: impl Fn(&mut Window, &mut gpui::App) -> Entity<V> + 'static,
) -> Self;
/// Unchanged sugar for a `Default` view.
pub fn root<V: Render + Default + 'static>(self, label: &'static str) -> Self;
}
Order inside Application::run:
setups (registration order) -> configured windows, in order:
window created, title set -> root builder -> window mapped
-> on_window_closed -> activate
A toolkit integration looks like this (illustrative, not compiled in this repository):
# app Cargo.toml - not Auro's
[package]
name = "log-viewer"
[dependencies]
auro = { path = "../auro/crates/auro" }
gpui-component = "=0.5.1"
use auro::prelude::*;
use gpui_component::{Root, Theme as KitTheme, ThemeMode};
fn main() {
App::new()
.setup(|cx, config| {
gpui_component::init(cx);
let mode = match config.app.windows[0].theme {
auro::Theme::Dark => ThemeMode::Dark,
auro::Theme::Light => ThemeMode::Light,
auro::Theme::System => ThemeMode::Light, // or follow the system appearance
};
KitTheme::change(mode, None, cx);
})
.root_with::<Root>("main", |window, cx| {
let view = cx.new(|_| LogViewer::default());
cx.new(|cx| Root::new(view, window, cx))
})
.run();
}
The app adds the toolkit, not Auro. If the toolkit does not need a custom root, root::<V> is still
enough and no wrapper is required.
app::tests::setup_runs_before_roots_and_root_with_uses_the_app_builder).root_with opens every declared window that has a root and uses the app's builder; the same
test asserts one window opens and the builder ran.root keeps its existing behavior; the window-title and window-options tests cover the shared
opener.Config reaching setup includes the declared theme; auro doctor reports a non-system theme
as toolkit-owned.docs/src/architecture/toolkits.md documents choosing a toolkit, the 0.5.x/0.10.x split,
and the measured size caveat; mdbook build docs passes.cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, and
cargo test --workspace --locked pass.| Question | Where it settles |
|---|---|
Whether to publish an optional auro-gpui-component integration crate | After the next GPUI line migration; ADR 0009 keeps the core toolkit-free meanwhile |
| How per-window themes map onto a toolkit with a global theme | App-level decision documented by the app; Auro passes the config through |
| Whether an optional toolkit integration should provide a shared theme bridge | Phase 3, if more than one toolkit needs it |
Status: Implemented (2026-11-17)
Phase 1 needs a way for an app to react to its own lifecycle: load data when it is ready, clean up when a window closes, and know when the last window is going away. This spec defines that contract. It is the first slice of the "lifecycle and app-wide events" item; user-defined app events are a separate spec.
LifecycleEvent enum in auro-core.App::on_lifecycle handlers, run on the main thread.Auro.toml.WindowManager).Exiting is informational in Phase 1.#![allow(unused)] fn main() { #[non_exhaustive] pub enum LifecycleEvent { Ready, WindowOpened { label: String }, WindowClosed { label: String }, Exiting, } }
LifecycleEvent::label() returns the label for window events. The enum lives in auro-core, so it
carries no renderer type; it is Clone, Debug, PartialEq and Eq for tests and logging.
App::on_lifecycle(|event, cx| ...) registers a handler. Handlers run synchronously on the GPUI
main thread, in registration order, with the app handle. They may update entities and managed state;
they must not block (the same rule as render). A panic propagates: Auro does not swallow lifecycle
handler failures.
Handlers are Fn, not FnOnce; they can be called once per event for the process lifetime.
At startup:
setups (registration order)
for each configured window, in declaration order:
window opens -> WindowOpened { label }
Ready
Closing:
WindowClosed { label } for each tracked window that disappeared
Exiting (only when no windows remain)
quit
If several tracked windows disappear between callbacks, each gets WindowClosed before Exiting.
Ready is emitted after the startup loop even if a window failed to open; the failure is logged by
the opener, not hidden.
The close path compares the handles Auro recorded when it opened each window against
cx.windows(). A window a toolkit or the app opened directly through GPUI is not tracked and emits
no WindowClosed; runtime opening through Auro arrives with the window manager, which must extend
this registry.
A configured window with no root view is not opened and emits no WindowOpened.
Exiting fires immediately before cx.quit() when the last window closes. It cannot veto or defer
the exit; a cancellable exit needs a return-value contract and belongs to a later lifecycle spec.
Ctrl-C, SIGTERM and platform termination are not lifecycle events in Phase 1.
Handlers and the handle registry are main-thread-only (Rc/RefCell internally). An app that wants
background work to react to lifecycle should send its own message to the main thread; Auro does not
expose a Send lifecycle receiver in this slice.
use auro::prelude::*;
App::new()
.on_lifecycle(|event, cx| match event {
LifecycleEvent::Ready => {
// load the app's data, update an entity, cx.notify()
}
LifecycleEvent::WindowClosed { label } => {
// release per-window resources
}
LifecycleEvent::Exiting => {
// final flush; cannot cancel
}
_ => {}
})
.root::<LogViewer>("main")
.run();
App::on_lifecycle is additive and chainable. Registration order is invocation order.
WindowOpened { label } before Ready;
the root builder runs after setups (app::tests::setup_runs_before_roots_and_lifecycle_reports_ready).WindowClosed and Exiting dispatch to handlers and preserve payloads
(app::tests::lifecycle_reports_window_close_and_exit).Ready/WindowOpened, and a real window close logs
WindowClosed/Exiting before exit. Recorded in the pull request; the close path remains a
manual run because GPUI's test platform does not simulate a compositor close.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Generic user-defined app event bus, background-to-main delivery | Next core spec |
Runtime WindowManager: open/close/focus by label; extend the registry | Phase 1 window spec |
Cancellable ExitRequested and platform termination events | Later lifecycle spec |
| Focus/resize/move events and per-window subscriptions | After the window manager |
Whether lifecycle handlers should receive &Config or a window handle | Revisit with the window manager |
Status: Implemented (2026-11-17)
Phase 1 needs app-wide notifications that cross the command boundary without strings. This spec fixes the event contract; ADR 0010 records why the channel and main-thread pump were chosen over a string bus, per-entity events or worker-thread callbacks.
EventSender: a cloneable, Send + Sync producer handle in auro-core.EventSender is automatically managed in the state store.App::on_event::<E> for main-thread handlers, registered before the app runs.emit(event, cx) for the main-thread path.An event is any E: Send + 'static. It is keyed by TypeId; two different types with the same
shape are different events. No string names exist.
emit(event, cx) dispatches synchronously to the registered handlers. Use it
from a view or lifecycle handler.EventSender::emit(event) boxes the event, queues it, and returns false when
the app is gone. The sender is available as State<EventSender> in commands and as a clone for
whatever else the app manages.The state store always contains one EventSender, inserted by App::new. A command can request
State<EventSender> without extra setup.
The facade installs a global EventBus and a foreground pump at App::run. The pump awaits the
unbounded channel and dispatches each event through AsyncApp::update, so handlers receive
&mut gpui::App and may update entities. Queued events are FIFO per producer. A main-thread
emit can interleave with the pump; there is no global order.
App::on_event::<E>(|event, cx| ...) registers a handler before run. Handlers run in
registration order, are Fn (called once per event), and must not block. A panic propagates. The
handler list is cloned before dispatch, so re-entrant emission (including a handler that closes a
window) is safe.
Events with no subscriber are dropped. An event for a type with no handler is not an error.
The channel is unbounded. A producer that outruns the main thread can grow memory. Apps that emit from a hot loop must rate-limit themselves. A bounded policy is a later decision.
use auro::prelude::*;
#[derive(Clone, Debug)]
struct ImportFinished { rows: usize }
#[auro::command]
async fn import(path: String, events: State<EventSender>) -> Result<usize, AuroError> {
let rows = 42;
let _ = events.emit(ImportFinished { rows });
Ok(rows)
}
fn main() {
App::new()
.on_event(|event: &ImportFinished, cx| {
// update an entity; cx.notify() schedules the repaint
})
.root::<LogViewer>("main")
.run();
}
// main-thread path, e.g. in a view or lifecycle handler
emit(ImportFinished { rows: 1 }, cx);
If the app needs a different queue policy, it can wrap EventSender in its own managed type; the
framework channel remains one option.
emit reaches the handler for its type and not the handler for another type
(app::tests::delivers_typed_events_and_keeps_types_isolated).EventSender::emit queues an event; the receiver yields it and dispatch calls the
handlers in registration order
(app::tests::queues_background_events_for_the_main_thread_pump).App::new manages an EventSender in the state store; the test obtains it with
State<EventSender>.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Backpressure/coalescing for hot producers | Later event-policy spec |
| Dynamic subscriptions with a handle/token | When a real app needs runtime subscribe |
| Cross-process/plugin event serialization and schema | Phase 3 plugin spec |
Whether lifecycle events should also flow through on_event | Keep separate: lifecycle is a closed enum with a different ordering contract |
| Event ordering across producers | App's responsibility; revisit if a framework primitive needs it |
Status: Implemented (2026-11-17)
Phase 0 made commands typed Rust functions and built a CommandHandler that dispatches by name.
Phase 1 adds the metadata that makes the handler useful outside first-party Rust: a JSON Schema for
each command's input and output. The handler is not wired into App yet; plugins are the consumer.
schemars 1.x as the schema source.#[auro::command] derives the input/output schema from the signature.CommandHandler stores and exposes per-command schemas.App or auto-generating docs from it (the handler remains a boundary
for plugins).$id and remote references.State<T> values; state is resolved, not sent.schemars is a dependency of auro-ipc and is re-exported as auro::ipc::schemars, so a consumer
does not need its own dependency for primitive arguments. A user argument type implements
schemars::JsonSchema; the generated code is a compile error otherwise. The output type comes from
Result<T, AuroError>; T must implement JsonSchema.
State<T> arguments are excluded from the input schema: they are resolved from the app, never sent
in the payload.
Input is a JSON Schema object:
{
"type": "object",
"properties": { "current": { "type": "integer", ... } },
"required": ["current"],
"$defs": { ... }
}
Property names use the command's rename_all setting. An argument whose schema accepts null is
optional and omitted from required; this covers Option<T> and unconstrained schemas such as
serde_json::Value. A $ref or other constrained schema stays required. Every other non-state
argument is required. State<T> is treated as managed state only when unqualified or written as
auro::State, auro::ipc::State or auro::prelude::State; a payload type such as
payload::State<T> is deserialized. A rename_all that maps two arguments to one key is a compile
error. Registering two commands with the same name is rejected (try_command returns a typed error;
the builder and generate_handler! panic with the name). Per-argument
$defs/definitions are hoisted to the root so #/$defs/... references resolve;
duplicate definition names are last-wins in this slice. Schemas are computed once when the handler
is built, not reflected at dispatch time.
Ok typeFor Result<T, AuroError>, the stored output schema is schema_for!(T). () is a valid output and
serializes as {"type":"null"}. The error shape is not part of the command output schema;
Response already carries the error kind/message.
CommandHandler::command(name, dispatch) remains for manual dispatch. The macro uses
command_with_schema(name, dispatch, input, output). Accessors:
schemas() -> impl Iterator<Item = &CommandSchema>schema(name) -> Option<&CommandSchema>CommandSchema { name, input, output } is public so a future plugin/docs consumer can serialize it.
A command registered without metadata has no schema entry; it still dispatches and appears in
names().
The handler stores serde_json::Value snapshots. Dispatch never re-runs schemars, so a command
call cannot fail because schema generation failed at runtime: derivation problems are compile-time.
#[auro::command(rename_all = "camelCase")]
async fn greet(first_name: String, count: u32) -> Result<Greeting, AuroError> { ... }
let handler = auro::generate_handler![greet];
let schema = handler.schema("greet").expect("registered with schema");
// schema.input["properties"]["firstName"]["type"] == "string"
// schema.output["$ref"] or the Greeting shape
#![allow(unused)] fn main() { pub struct CommandSchema { pub name: &'static str, pub input: serde_json::Value, pub output: serde_json::Value, } impl CommandHandler { pub fn command_with_schema( self, name: &'static str, dispatch: impl Fn(Invoke) -> ResponseFuture + Send + Sync + 'static, input: serde_json::Value, output: serde_json::Value, ) -> Self; pub fn schemas(&self) -> impl Iterator<Item = &CommandSchema> + '_; pub fn schema(&self, name: &str) -> Option<&CommandSchema>; } }
properties, listed in required; an Option<T> argument is not listed in required.State<T> arguments do not appear in the input schema.rename_all = "camelCase" changes the property key.Ok type; () becomes a null schema.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
Wiring the registry into App and generated docs | Plugin/docs slice |
| Schema negotiation, versioning and compatibility | Phase 3 plugin spec |
| Definition-name collisions when two types share a name | Revisit when struct args are used in the wild |
| Optional command arguments | Later command-contract change |
$id and cross-file references | Not planned for 1.0 |
Status: Implemented (2026-11-17)
The lifecycle slice tracks the windows Auro opens and reports their close. Phase 1 also needs the
app to act on a window by its configured label: open a settings window from a menu, focus it, close
it, and know whether it is open. This spec fixes that contract for windows declared in Auro.toml.
App::run.open, close, focus, is_open and handle by configured label.LifecycleEvent::WindowOpened / WindowClosed / Exiting.Auro.toml.A window is identified by the label declared in app.windows. The configuration is
authoritative: open requires a declared label with an attached root. Two windows with the same
label are rejected by config validation, so the manager stores at most one handle per label.
App::run installs a main-thread WindowManager global before setups, holds the parsed config, the
root builders, the lifecycle dispatcher and the same handle registry the close observer uses. This
is why the close observer and the manager cannot drift: they share the registry.
The manager is not available before App::run; calling a window function then is a programming
error and panics with a clear message, like emit before the event bus is installed.
windows::open(label, cx):
AuroError::Window { label, message };WindowOpened;LifecycleEvent::WindowOpened { label } and returns the handle.Opening does not focus the window unless the root/GPUI does so; focus is explicit.
windows::close(label, cx) removes the GPUI window. The existing close observer attributes the
disappearance to the label, emits WindowClosed, and emits Exiting if it was the last window.
close returns false when the label is unknown or not open; it does not panic.
focus(label, cx) activates the window (Window::activate_window) and returns false when it
is not open.is_open(label, cx) checks the live GPUI window list, not just a stale registry entry.handle(label, cx) returns the current AnyWindowHandle.All are main-thread only. None blocks or performs I/O.
App::run still opens every configured window that has a root, in declaration order, through the
manager's open path, then emits Ready. The manager therefore owns the startup open as well;
there is one code path for initial and later opens.
use auro::{prelude::*, windows};
fn open_settings(cx: &mut gpui::App) {
match windows::open("settings", cx) {
Ok(_) => {}
Err(error) => eprintln!("settings: {error}"),
}
}
fn close_settings(cx: &mut gpui::App) {
let _ = windows::close("settings", cx);
}
fn focus_settings(cx: &mut gpui::App) -> bool {
windows::focus("settings", cx)
}
let open = windows::is_open("settings", cx);
let handle = windows::handle("settings", cx);
AuroError::Window { label, message } has kind "window"; the message names the label and whether
it is undeclared or has no root.
AuroError::Window; opening a declared label with no root
returns the same type.WindowOpened once.WindowClosed; closing the last window emits
Exiting through the existing close observer.WindowOpened again.focus returns true for an open window and false otherwise; is_open/handle agree with
cx.windows().cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Focus/resize/move events and per-window subscriptions | After this slice |
| Window position/size persistence across runs | Platform-services slice |
| Modal parent/child relationships | Platform-services slice |
| Preventing close or exit | Later lifecycle spec |
| Multiple instances of one label (e.g. an untitled document window) | Needs an instance id, not a label; later |
Status: Implemented (Linux, Windows and macOS verified 2026-11-17)
Phase 2 needs installable artifacts. Auro does not write a bundler: auro-bundle maps the
[bundle] section of Auro.toml onto tauri-bundler 2.10 and delegates the platform formats to it
(ADR 0011).
auro-bundle crate: config-to-bundler mapping and artifact paths.auro bundle CLI command: release build, then bundle.app/dmg, Windows msi/nsis, Linux appimage/deb/rpm.AuroError::Bundle).[bundle].icon.tauri-bundler, pinned exactlytauri-bundler = "=2.10.5" is pinned in the workspace. Its own documentation warns that minor
releases may change the API; an upgrade is a deliberate change that must run the three-OS CI. The
bundler crate is an implementation detail of auro-bundle, not Auro's public API.
auro-bundle reads the already-validated Config. It does not read Cargo.toml package metadata
except through the binary name the CLI supplies. Mapping:
Auro.toml | tauri-bundler |
|---|---|
app.identifier | BundleSettings::identifier |
app.product-name | PackageSettings::product_name |
app.version | PackageSettings::version |
app.description | PackageSettings::description (product name when empty) |
app.authors / app.homepage | PackageSettings fields; homepage also in bundle settings |
app.license | BundleSettings::license |
bundle.category | BundleSettings::category (AppCategory) |
bundle.short-description / long-description | bundle settings |
bundle.copyright / license-file | bundle settings |
bundle.icon / resources | absolute paths derived from the app directory |
bundle.targets | PackageType list; "all" uses the host set |
An unknown category or package format is AuroError::Bundle, not a bundler panic.
auro bundle builds firstauro bundle loads and version-checks the config, rejects a config with
[bundle] active = false (AuroError::Bundle; bundling is opt-out, not a silent no-op), runs
cargo build --release, resolves the executable name through cargo metadata (default-run, else
the sole enabled binary target, including auto-discovered src/bin/*.rs; targets whose
required-features are disabled are ignored, an explicit --bin in [dev].build-args wins, and
several enabled binaries without default-run are an error naming only those candidates), then
calls
auro_bundle::bundle_in(dir, &config, &binary, &target). The target root is
CARGO_TARGET_DIR resolved like cargo (relative values under the invocation directory), or
<app>/target; the bundler reads <target>/release and artifacts land under
<target>/release/bundle/<format>/. Every produced path is printed, one per line; an empty
artifact list is a typed AuroError::Bundle, not a successful no-op.
The app directory is canonicalised, so bundler paths are stable regardless of where the command is run.
Phase 2 supports the host's formats. bundle.targets is already validated per host in spec 0002;
"all" resolves to the host set. Cross-compilation is not a supported CLI workflow and is not a
claim; the bundler's experimental warning is not suppressed.
auro bundle does not configure signing identities, certificates, notarization or an updater.
tauri-bundler may sign when the host environment provides credentials; Auro does not promise it.
The signing spec and the updater spec own those contracts.
pub fn host_targets() -> &'static [&'static str];
pub fn package_types(config: &Config) -> Result<Vec<PackageType>, AuroError>;
pub fn bundle(dir: &Path, config: &Config, binary: &str) -> Result<Vec<PathBuf>, AuroError>;
auro bundle [--dir <app>]
AuroError::Bundle { message } has kind "bundle".
PackageTypes; "all" maps to the host set
(auro-bundle unit tests).maps_the_manifest_metadata).rejects_an_unknown_category).binary_name resolves from cargo metadata, including auto-discovered src/bin targets, honors
required-features and [dev].build-args (including --bin), and rejects several enabled
candidates without default-run (auro-cli tests).auro bundle on a real scaffolded app builds release and produces the host's requested
artifacts, printing their paths. Recorded with host, formats and environment.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.Linux verified on x86_64 with tauri-bundler 2.10.5. A fixture app (plain release binary,
targets = ["deb", "rpm", "appimage"], a 512x512 PNG icon) produced:
target/release/bundle/deb/Bundle Demo_0.1.0_amd64.deb
target/release/bundle/rpm/Bundle Demo-0.1.0-1.x86_64.rpm
target/release/bundle/appimage/Bundle Demo_0.1.0_amd64.AppImage
auro bundle printed each path. A missing/non-square AppImage icon is rejected before the bundler
runs, because tauri-bundler panics in that case. macOS .app/.dmg are wired through the same
mapping but have not been produced on that host in this environment; the three-OS CI is the place
to verify them.
Windows 11 x86_64 (WinBoat guest, rustc/cargo 1.99.0 MSVC, tauri-bundler 2.10.5) verified the
same mapping with targets = ["msi", "nsis"] and a 256x256 .ico:
target\release\bundle\msi\Bundle Demo_0.1.0_x64_en-US.msi (0.61 MB)
target\release\bundle\nsis\Bundle Demo_0.1.0_x64-setup.exe (0.17 MB)
The MSI installed silently, ran bundle-demo.exe (bundle demo on windows), and uninstalled
cleanly; the NSIS setup installed per-user, ran the same binary, and uninstalled. The NSIS
uninstaller finishes asynchronously, so the install directory disappears a few seconds after the
uninstaller returns.
Windows installers set webview_install_mode = Skip because Auro's app layer has no webview;
otherwise the Tauri template tries to download/install WebView2. Two Windows-only path issues were
fixed in the same change: the bundler call now runs with the app directory as cwd (icons/resources
resolve relative to it) and canonicalize's \\?\ verbatim prefix is stripped before WiX/NSIS
tools see it.
macOS verification (unsigned, no local Mac): the bundle-smoke
workflow ran on a GitHub macos-latest arm64 runner. A fixture app with targets = ["app", "dmg"]
and a 512x512 PNG icon produced:
target/release/bundle/macos/Bundle Smoke.app
target/release/bundle/dmg/Bundle Smoke_0.1.0_aarch64.dmg
The workflow ran the app binary and accepted the DMG with hdiutil imageinfo. No signing identity
is configured, so the artifacts are unsigned; signing/notarization belong to the signing spec.
| Question | Where it settles |
|---|---|
| Codesign/notarization and Windows signing | macOS notarization and signing spec |
| Package-manager apply and restart/rollback orchestration | Linux packages, elevation; deltas/rollout are spec 0028 |
| Icon placeholders in the scaffold | Bundling follow-up; apps may supply icons today |
| Cross-compilation | Not planned for 1.0; revisit if demand appears |
| AppImage tool downloads and offline builds | Document the bundler's cache/tooling behavior |
Status: Implemented (2026-11-17; platform signing delegated, notarization credentials not exercised)
Phase 2 needs signed artifacts and a root of trust for update manifests. Auro owns the key format
and the manifest signature; it delegates OS code signing to the platform toolchain through
tauri-bundler (ADR 0011, ADR 0012).
auro-sign: Ed25519 signing keys, signatures, SHA-256 file hashes and key files.[bundle.macos] and [bundle.windows] config keys mapped to the bundler.auro generate-key --out <path>.A secret key is a 32-byte Ed25519 seed. The key file is:
# Auro signing key v1
<base64 seed>
auro generate-key writes it with owner-only permissions on Unix and prints the public key. A
public key is base64 of 32 bytes; a signature is base64 of 64 bytes. Debug output never prints the
seed. Verification uses verify_strict, so malleable signatures are rejected.
auro-sign::sha256_file produces lowercase hex. Manifests carry the digest and size; the signature
covers the manifest payload, not the artifact directly.
[bundle.macos] maps to MacOsSettings (signing_identity, entitlements, hardened
runtime, skip stapling). Notarization uses the bundler's environment contract
(APPLE_ID/APPLE_PASSWORD/APPLE_TEAM_ID); no credentials are config keys.[bundle.windows] maps to WindowsSettings (certificate thumbprint, digest algorithm,
timestamp URL/TSP, custom sign command + args, downgrade policy). WebView2 remains skipped.codesign/signtool itself; the bundler owns the platform commands.Key files and certificates are outside the app source tree and CI secrets. auro bundle works
unsigned when no identity is configured; the macOS smoke workflow exercises exactly that path.
#![allow(unused)] fn main() { pub struct SigningKey; impl SigningKey { pub fn generate() -> Self; pub fn from_seed_base64(seed: &str) -> Result<Self, SignError>; pub fn seed_base64(&self) -> String; pub fn public_key(&self) -> PublicKey; pub fn sign(&self, bytes: &[u8]) -> String; pub fn load_from(path: &Path) -> Result<Self, SignError>; pub fn save_to(&self, path: &Path) -> Result<(), SignError>; } pub struct PublicKey; impl PublicKey { pub fn from_base64(key: &str) -> Result<Self, SignError>; pub fn to_base64(&self) -> String; pub fn verify(&self, bytes: &[u8], signature: &str) -> Result<(), SignError>; } pub fn sign_file(key: &SigningKey, path: &Path) -> Result<String, SignError>; pub fn verify_file(key: &PublicKey, path: &Path, signature: &str) -> Result<(), SignError>; pub fn sha256_file(path: &Path) -> Result<String, SignError>; }
auro generate-key --out release.key
auro-sign tests).key_file_round_trips_with_owner_only_permissions).signs_and_verifies_a_file_and_hashes_it).[bundle.macos]/[bundle.windows] values reach the bundler settings
(auro-bundle maps_signing_settings).auro generate-key writes a loadable key (auro-cli test).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Keychain/HSM-backed keys | Platform-services/keychain slice |
| Notarization credential wiring and CI secret setup | Signing CI follow-up |
| Windows certificate provisioning and signtool verification | Windows signing follow-up |
| Key rotation and revocation | Updater/trust spec |
| Timestamp format for manifests | Spec 0012 / update service |
Status: Implemented (manifest format v2, signing, verification and CLI; runtime download/staging is spec 0013; deltas/rollout are spec 0028; platform apply is spec 0014/0025)
Phase 2 needs a signed description of a release artifact. This spec fixes the manifest format and its verification; the runtime is specified separately (0013 covers check/download/stage and 0014 the first apply path).
auro-update: manifest format v2, signing, verification, JSON encode/decode.auro manifest --artifact ... --key ... --out ... to produce a signed manifest.<os>-<arch>) and publication timestamps as caller-supplied text.{
"format": 2,
"version": "1.2.3",
"platform": "linux-x86_64",
"url": "https://example.test/app-1.2.3.tar.gz",
"size": 42,
"sha256": "...",
"notes": "...",
"published_at": "2026-11-17T12:00:00Z",
"signature": "<base64 Ed25519 signature>"
}
delta and rollout are omitted when absent. Unknown fields are rejected. format other than 2 is
an unsupported-format error, not a guess. Format v1 manifests are rejected by this build.
sha256 is exactly 64 lowercase hexadecimal characters; verification rejects anything else before
hashing an artifact.
The payload is the same fields without signature, serialized with serde_json in the struct's
field order, including any present delta/rollout fields. The signature is Ed25519 over those bytes. A field reorder or rename is a format
change; bump format and migrate. Manifest::verify checks format, presence of a signature, then
the signature.
Manifest::for_artifact reads the local file, records its byte length and SHA-256.
Manifest::verify_artifact verifies the manifest signature first, then size and hash. A signed
manifest for a different file fails.
auro generate-key --out release.key
auro manifest \
--artifact target/release/bundle/app.tar.gz \
--version 1.2.3 \
--url https://example.test/app.tar.gz \
--key release.key \
--out latest.json \
--notes "..." \
--published-at 2026-11-17T12:00:00Z \
[--platform linux-x86_64]
The platform defaults to <std::env::consts::OS>-<std::env::consts::ARCH>. The command prints the
manifest path.
The signature and hash prevent a tampered manifest/artifact from being accepted. Spec
0013 downloads and stages a verified artifact; spec
0014 replaces a Linux AppImage and spec 0025
runs Windows installers or replaces a macOS .app. Package-manager apply remains separate, and
nothing restarts or replaces a running app automatically.
#![allow(unused)] fn main() { pub struct Manifest { pub format: u32, pub version: String, pub platform: String, pub url: String, pub size: u64, pub sha256: String, pub notes: String, pub published_at: String, pub delta: Option<Delta>, pub rollout: Option<Rollout>, pub signature: String, } impl Manifest { pub fn new(...) -> Self; pub fn for_artifact(...) -> Result<Self, UpdateError>; pub fn with_delta(self, delta: Delta) -> Self; pub fn with_rollout(self, rollout: Rollout) -> Self; pub fn sign(self, key: &SigningKey) -> Result<Self, UpdateError>; pub fn verify(&self, key: &PublicKey) -> Result<(), UpdateError>; pub fn verify_artifact(&self, path: &Path, key: &PublicKey) -> Result<(), UpdateError>; pub fn to_json(&self) -> Result<String, UpdateError>; pub fn from_json(text: &str) -> Result<Self, UpdateError>; } }
signs_and_verifies_a_manifest,
rejects_a_tampered_field).rejects_an_empty_signature_and_unknown_format, rejects_a_malformed_artifact_hash).verifies_an_artifact_and_its_metadata).json_round_trips).auro-cli release test).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Download/apply/staging/restart and rollback | Updater runtime / AppImage / Windows and macOS / journal and restart |
| Deltas/patches and staged rollout percentages | Binary deltas and staged rollout |
| Key pinning and rotation inside the app | Trust/update client spec |
| Update channels and UI | Platform/update UX follow-up |
| Hosting/CSP and mirror behavior | Release service follow-up |
Status: Implemented (2026-11-18; full and delta staging and staged rollout; platform apply is spec 0014/0025; package-manager apply and helper-side apply are separate; Linux package elevation is spec 0029)
Spec 0012 fixes the signed manifest. This spec fixes the first runtime half: deciding whether an offer is acceptable, downloading it, verifying the bytes and putting a verified artifact in a staging directory. Installation starts in spec 0014 for AppImage and spec 0025 for Windows/macOS.
auro-update::Updater: a pinned public key, the running semantic version, the host platform and a
staging directory.check: manifest signature, format, platform and semantic-version comparison.download: HTTP(S) fetch of a newer artifact, with a bounded body and exact manifest size.stage_from_path: the same verification and staging path for an artifact already on disk.check verifies the manifest signature and format, rejects a platform that is not this build, and
parses both versions as semantic versions. It returns one of three decisions:
| Decision | Meaning | download behavior |
|---|---|---|
UpToDate | offered version equals the running version | refuses |
Available | offered version is newer | downloads/stages |
Downgrade | offered version is older | refuses |
A signed older manifest can be replayed, so downgrade is a decision for a caller that has an
explicit rollback policy; the default runtime never stages it. The explicit rollback entry points
are stage_rollback_from_path/download_rollback in
spec 0030, which require a strictly older signed version. A
malformed version is a typed error, not a lexical comparison.
Rejected: comparing version strings. 1.10.0 sorts before 1.9.0 lexically. Rejected:
accepting a manifest for another platform and letting the installer fail later.
The staged filename is the lowercase artifact SHA-256, plus the URL's extension when it is a short
ASCII-alphanumeric token. The hash is the identity: two manifests with different bytes cannot
collide, and the URL cannot inject a path. Manifest::verify now rejects a SHA-256 that is not 64
lowercase hexadecimal characters before any artifact or path work happens.
Existing staged bytes are reused only when the manifest signature, size and SHA-256 all verify.
Rejected: using the last URL path segment as the filename. It is attacker-controlled and can contain traversal or platform-reserved names.
The artifact is written to a temporary file in the staging directory. The reader is limited to the
manifest size; one additional byte is read to reject an oversized body. A short body is an
ArtifactSize error. The temporary file is synced, verified against the manifest's size and
SHA-256, then persisted at its content-addressed path. A failed download publishes nothing: the
temporary file is dropped, and a previously staged file is left untouched. Verification compares
the file length from metadata and hashes in 64 KiB chunks, so its memory use is independent of the
artifact size; reused staged files and delta patches follow the same rule. A delta is applied
directly into the staging temp file (the base and patch are still read into memory because the
bsdiff API takes slices), and the resulting file is verified before it is published.
Rejected: downloading to the final path and verifying afterwards. A crash or a failed hash would leave a plausible-looking but unusable file.
Downloads use ureq 3 with rustls and the webpki roots. The agent uses a 10 s connect timeout, a
300 s per-call timeout and a 30 s per-read timeout; the manifest size bounds the body. Redirects
use ureq's default limit. HTTP URLs are accepted because the signature is the trust boundary;
production channels should use HTTPS, while tests and local mirrors may use HTTP.
Rejected: adding a second HTTP stack (for example reqwest) for one GET. ureq is already in the
workspace through the bundler.
Manifest v2 adds base-bound bsdiff-compatible deltas and deterministic percentage rollout. Full staging remains the fallback. The runtime verifies the base, patch and resulting full artifact before publishing it. Details are in spec 0028.
StagedUpdate exposes the manifest and the verified path, and nothing else. Applying an update is
a separate contract because it differs per artifact (AppImage replacement, MSI/NSIS execution,
macOS app replacement) and needs a restart/rollback protocol. The Linux AppImage path is
spec 0014; this slice still runs no installer and replaces no binary.
Rejected: a generic "run this command" install hook in the framework. It moves platform policy into every app and makes rollback unverifiable.
#![allow(unused)] fn main() { pub enum UpdateDecision { UpToDate, Available, Downgrade, } pub struct Updater { /* staging dir, key, current version, platform, HTTP agent */ } impl Updater { pub fn new( staging_dir: impl Into<PathBuf>, key: PublicKey, current_version: &str, ) -> Result<Self, UpdateError>; pub fn with_platform(self, platform: impl Into<String>) -> Self; pub fn current_version(&self) -> &semver::Version; pub fn platform(&self) -> &str; pub fn check(&self, manifest: &Manifest) -> Result<UpdateDecision, UpdateError>; pub fn download(&self, manifest: &Manifest) -> Result<StagedUpdate, UpdateError>; pub fn stage_from_path( &self, manifest: &Manifest, artifact: &Path, ) -> Result<StagedUpdate, UpdateError>; } pub struct StagedUpdate { /* manifest, path */ } impl StagedUpdate { pub fn manifest(&self) -> &Manifest; pub fn path(&self) -> &Path; pub fn into_parts(self) -> (Manifest, PathBuf); } }
Errors added to UpdateError: InvalidField, InvalidVersion, PlatformMismatch, NotNewer,
ArtifactTooLarge and Http. Manifest::verify also rejects a malformed SHA-256.
Usage:
let key = auro::update::PublicKey::from_base64(&app.public_key)?;
let updater = auro::update::Updater::new(
state_dir.join("updates"),
key,
env!("CARGO_PKG_VERSION"),
)?;
let manifest = auro::update::Manifest::from_json(&body)?;
if updater.check(&manifest)? == auro::update::UpdateDecision::Available {
let staged = updater.download(&manifest)?;
// An install step consumes `staged` in a later slice.
}
The snippet documents the intended call shape; its surrounding app code does not exist yet. Enable
the facade's updater feature (or depend on auro-update directly) to use the module.
Available, UpToDate and Downgrade; a
different platform and an invalid version fail with typed errors
(classifies_versions_and_rejects_a_different_platform,
rejects_invalid_versions_and_bad_current_version).verifies_before_touching_the_network).download stages it under <sha256>.<ext>, the
manifest verifies the staged file, and a second call reuses it without another request
(downloads_verifies_and_reuses_a_staged_artifact).ArtifactHash; a short body with ArtifactSize; an oversized
body with ArtifactTooLarge; none leaves a final artifact
(rejects_tampered_short_and_oversized_downloads).refuses_to_stage_an_up_to_date_version).stage_from_path copies and verifies a local artifact (stages_a_local_artifact).Manifest::verify rejects a SHA-256 that is not 64 lowercase hexadecimal characters
(rejects_a_malformed_artifact_hash).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Install/restart/rollback by platform | AppImage apply / Windows and macOS apply / restart spec |
| Deltas and staged rollout selection | Binary deltas and staged rollout |
| Persistent update journal and resume | Update journal / resume spec |
| Key rotation/revocation and pinning in the app | Trust/update client spec |
| Update channels, prompts and scheduling | Platform/update UX follow-up |
Status: Implemented (2026-11-17; Linux AppImage only; Windows/macOS apply is spec 0025, restart handoff is spec 0026; helper-side apply and package-manager installers are separate; elevation is spec 0029)
Spec 0013 stops at a verified staged artifact. This spec adds the first apply path: replacing a single-file Linux AppImage, with a receipt that can roll the previous file back. It deliberately does not generalise installation into a command hook.
auro-update::AppImageInstaller: install a staged artifact over an existing AppImage.InstallReceipt: report the installed target and retained backup, roll back, or discard the
backup..deb/.rpm package installation, macOS .dmg/.pkg, and the Windows/MSI/NSIS and macOS
.app details owned by spec 0025.StagedUpdate.An AppImage is one executable file on Linux. Installation resolves the target through symlinks,
writes the staged bytes to a temporary file in the target directory, sets mode 0755, syncs it,
and renames it over the target. On Linux, the running process keeps the old inode, so replacing a
running AppImage is safe; the new file is used on the next launch.
Rejected: extracting or patching the AppImage. Auro ships the whole artifact and verifies its hash in the staging layer.
The old target is retained beside the installed file. A hard link is preferred because it is instant and preserves the old inode and metadata; a copy is the fallback for filesystems without hard links. The backup path is hidden, name-scoped to the target, and unique per process/timestamp.
InstallReceipt owns the backup. Dropping it does not delete the backup: an app must choose
discard after verifying the new version, or rollback to restore. This makes the default failure
mode conservative, at the cost of leaving a backup until the app acts.
InstallReceipt::rollback renames the backup over the target. A missing backup is a typed error and
leaves the installed file in place. The receipt is consumed; a caller that needs to retry can
inspect the path before consuming it. discard removes the backup and is idempotent.
Rejected: deleting the old file immediately. A bad update would then require re-downloading the old release, which may no longer be served.
AppImageInstaller and InstallReceipt are compiled only on Linux. Windows installers, macOS app
bundles and distribution packages have different restart, privilege and rollback requirements and
get their own contracts. Auro does not expose a "run this command to install" hook, which would move
platform policy into every app and make rollback unverifiable.
Installing does not relaunch the app or wait for it to exit. The caller decides when to restart
after installation and when to call discard. A restart/helper protocol is a separate slice.
#![allow(unused)] fn main() { pub struct AppImageInstaller { /* target path */ } impl AppImageInstaller { pub fn new(target: impl Into<PathBuf>) -> Self; pub fn target(&self) -> &Path; pub fn install(&self, staged: &StagedUpdate) -> Result<InstallReceipt, UpdateError>; } pub struct InstallReceipt { /* installed target, backup */ } impl InstallReceipt { pub fn target(&self) -> &Path; pub fn backup(&self) -> &Path; pub fn rollback(self) -> Result<(), UpdateError>; pub fn discard(self) -> Result<(), UpdateError>; } }
Errors added to UpdateError: InstallTargetMissing, InstallTargetNotFile,
StagedArtifactMissing and RollbackBackupMissing.
Usage:
let staged = updater.download(&manifest)?;
let receipt = auro::update::AppImageInstaller::new(current_appimage).install(&staged)?;
// Restart into the new version, then:
receipt.discard()?;
The snippet is an intended call shape, not code that exists as an app.
0755, and retains the old bytes in the
receipt's backup; rollback restores the old bytes and mode
(installs_and_rolls_back_an_appimage).discard removes the backup and leaves the installed file (discards_the_backup_after_success).rejects_a_missing_or_non_file_target).missing_staged_artifact_leaves_the_target_untouched).RollbackBackupMissing and leaves the installed file
(rollback_reports_a_missing_backup).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Windows MSI/NSIS apply and privilege handling | Windows and macOS apply / Windows UX |
macOS .dmg/.pkg replacement and notarization | macOS updater spec |
.deb/.rpm package-manager updates | Linux package apply |
| Restart/helper protocol and crash-safe receipt | Update journal and restart helper |
| Preserving xattrs, SELinux labels and ownership | Platform apply hardening |
| Rollout, deltas and downgrade policy | Updater rollout spec |
Status: Implemented (2026-11-17; duplicate prevention, argument forwarding and opt-in activation helper)
Phase 2 needs every app to be able to enforce one running instance. A process holds an advisory lock
for its configured app identifier; a second process detects that it is secondary before GPUI starts,
forwards its arguments and working directory over a local socket, and exits. The primary receives a
typed [InstanceMessage] on its normal event pump.
auro-core::AppInstance: acquire an advisory per-user file lock and report primary/secondary.InstanceMessage: forwarded arguments and working directory.App::single_instance(): opt in when building an app; forwarding requires no app code.App::activate_on_second_instance(): opt-in focus of the first root window on a forwarded
launch.InstanceListener: keeps the primary lock and forwarding thread alive.AuroError::Instance before any window opens on the secondary.App::activate_on_second_instance() focuses the first root by
default, while apps with other needs use InstanceMessage and on_event.AppInstance opens a lock file and calls File::try_lock. TryLockError::WouldBlock means another
process holds it; any other error is an AuroError::Instance. The lock is released when the file is
closed, including on a crash; the lock file remains on disk and is reused.
Rejected: a PID file. A stale PID can belong to an unrelated process after reboot, and checking it is racy. Rejected: a TCP listener; a local socket has no ports, firewall rules or network exposure.
The path is auro-<sanitised-id>-<hash>.lock. The identifier is sanitised to ASCII alphanumerics,
., - and _ and truncated to 128 characters, so it cannot escape the directory; a stable
16-hex-digit FNV-1a hash of the full identifier follows the truncation, so two identifiers that
share their first 128 characters use different locks. On Unix the file is created with mode
0600. The directory is XDG_RUNTIME_DIR when it is a real directory owned by this user
with no group/other permission bits; otherwise the process uses a private auro-<uid> subdirectory
of the temporary directory, created with mode 0700 and re-validated (ownership, owner-only mode,
not a symlink) before use. The identifier is normally app.identifier from Auro.toml.
On a shared /tmp, a predictable name alone is not enough: another local user could pre-create the
directory, lock file or socket and receive forwarded arguments. An XDG_RUNTIME_DIR that fails the
check is ignored in favor of the fallback; a fallback directory that fails is refused with
AuroError::Instance. An attacker who pre-creates the per-user directory can still deny
single-instance operation (the app refuses to start that guard), which is a denial of service, not
an information leak. Interference by a same-user process remains outside the threat model.
The secondary acquires the lock (finding it already held), forwards InstanceMessage { args, cwd },
and returns AuroError::Instance before GPUI starts. App::run prints it and exits with code 2. The
primary receives the message on its event pump. App::activate_on_second_instance() opts into
focusing app.default-window (the first declared window when the key is unset) and activating the
app; apps that need another window use InstanceMessage and on_event.
Rejected: returning success from the secondary process. It would hide a user's attempted launch and make automated tests unable to distinguish "opened" from "refused".
Single-instance is enabled with App::single_instance(); the default is off. An app that wants
multiple independent windows/processes, or a CLI mode, is not forced into the guard. This mirrors the
app model's preference for explicit capabilities over invisible global policy.
The lock and listener are acquired after config load and before Application::new().run, and are
held until try_run returns. Dropping the guard closes the lock; dropping the listener detaches the
forwarding thread and the process exit releases the socket. Neither is stored in managed state.
On Unix the primary binds a filesystem socket in the per-user runtime directory selected by D2 (name
derived from a short sanitised prefix plus a stable hash of the full identifier, so long
reverse-DNS identifiers sharing a prefix cannot collide and the path stays inside sun_path); Linux applies
mode 0600, and macOS uses the private directory under its per-user $TMPDIR. Windows uses a
named pipe with the same label. The listener accepts connections in a background thread, reads one
message, and sends the decoded InstanceMessage to the app's EventSender.
Two wire formats are accepted for one release: alpha.2's newline-delimited JSON and alpha.3's
8-byte big-endian length followed by JSON. The first byte distinguishes them ({ or whitespace is
legacy JSON; a length prefix is binary). A framed message is acknowledged with one 0x06 byte
after the message is queued. A single handler worker drains the queue, so a slow app handler cannot
stall the listener, delay the acknowledgement, or cause the legacy retry to duplicate a launch. Each
accepted connection is parsed on its own thread with a 5 s receive timeout where the platform
supports one, so a sender that dies mid-frame cannot block later launches or their acknowledgement.
Each accepted connection carries an accept-order sequence; the dispatcher delivers messages in that
order, skips a sequence that does not complete within 2 s, and drops a late result rather than
delivering it out of order. A secondary tries the frame first and, if no acknowledgement arrives
within 2 s, reconnects and writes the alpha.2 line. This lets alpha.4 forward to an alpha.2
primary (line fallback) and to an alpha.3 primary (frame accepted, legacy retry discarded), while
alpha.2 and alpha.3 secondaries can forward to alpha.4. Windows named pipes expose no receive
timeout, so the Windows secondary uses the legacy line directly.
The payload limit is 1 MiB. forward serialises first and returns AuroError::Instance for an
oversized message instead of writing a truncated frame and exiting as if delivery succeeded; the
listener independently rejects an oversized declared length or line. The limit replaces the former
64 KiB read, which silently truncated and dropped long launch arguments.
This avoids an abstract Linux socket, which has no filesystem permissions: a different local user
could otherwise inject messages. ListenerOptions::try_overwrite handles a stale socket name; the
file lock remains the authority that prevents two primaries. Invalid JSON is logged and never
invokes the app handler.
On Windows the named pipe is machine-global rather than behind a per-user directory; isolation relies on the pipe's default ACL, and multi-user behavior has not been verified on a real desktop session. The forwarded payload is arguments and a working directory, never secrets by contract.
Rejected: a shared-memory or file-drop protocol. It needs polling or a second notification channel and is harder to test than a local socket. Rejected: an abstract socket, because peer credentials would become a second authentication path.
#![allow(unused)] fn main() { pub struct InstanceMessage { pub args: Vec<String>, pub cwd: PathBuf, } pub struct AppInstance { /* file, path, name, primary */ } impl AppInstance { pub fn acquire(name: &str) -> Result<Self, AuroError>; pub fn is_primary(&self) -> bool; pub fn name(&self) -> &str; pub fn path(&self) -> &Path; pub fn forward(&self, message: &InstanceMessage) -> Result<(), AuroError>; pub fn listen( self, handler: impl Fn(InstanceMessage) + Send + 'static, ) -> Result<InstanceListener, AuroError>; } pub struct InstanceListener { /* guard, thread */ } impl App { pub fn single_instance(self) -> Self; pub fn activate_on_second_instance(self) -> Self; pub fn on_event<E: Send + 'static>( self, handler: impl Fn(&E, &mut GpuiApp) + 'static, ) -> Self; } }
AuroError gains Instance { name, message } with kind "instance".
Usage:
App::new()
.activate_on_second_instance()
.root::<View>("main")
.run();
// Or handle the forwarded launch yourself:
App::new()
.single_instance()
.on_event(|message: &auro::InstanceMessage, cx| {
let _ = auro::windows::focus("main", cx);
})
.root::<View>("main")
.run();
first_guard_is_primary_and_second_is_not).InstanceMessage to the primary listener
(forwards_a_message_to_the_primary_listener).primary_cannot_forward_or_secondary_cannot_listen).AuroError::Instance (empty_name_is_rejected).path_is_sanitised).App::single_instance() is opt-in and sets the builder flag; the activation helper enables
both flags (single_instance_is_opt_in).AuroError::Instance reports kind "instance" and includes name/message
(instance_errors_have_context_and_kind).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Custom activation behavior | App policy / on_event |
| File and deep-link routing into the primary | Deep-link and instance IPC follow-up |
| Lock/socket cleanup policy | Operations follow-up |
| Stable IPC protocol for third-party clients | Revisit only if required |
| Windows/macOS behavior under real desktop sessions | Platform audit |
Status: Implemented (2026-11-17)
Auro does not sandbox first-party app code. This spec fixes the smallest runtime contract for the real boundaries: plugins, untrusted content and the webview escape hatch. It is deny-by-default, compiled into the host, and checked at the call site that performs the effect.
auro-perms: a Policy with deny-by-default grants for fs, net, shell, clipboard,
notification and keychain.fs, net, shell) match a glob pattern against the value being acted on.Denied errors naming subject, capability and value.auro::perms re-export for app and host code.Policy in code today.Policy::deny_all() has no grants. Every check without a matching grant is a typed denial. There is
no global allow-all mode, because the boundary exists precisely so a subject can be constrained.
Rejected: an implicit allow for first-party code. The policy is used at call sites that perform an effect on behalf of a subject, so a missing grant must be an error, not a shortcut.
fs, net and shell are scoped. Grant::scoped(subject, capability, pattern) compiles a
globset pattern once and rejects malformed patterns at grant time. Policy::check_scope(subject, capability, value) matches the value against the compiled form; it never re-parses the pattern per
call.
A filesystem value must be rooted (absolute, or a leading separator) with no . or ..
components. The match is lexical, so /var/lib/notes/../secret would otherwise match
/var/lib/notes/** and escape the grant. A shell value must have no ./.. components either,
but may be a bare executable name; a full command string must be parsed and validated by the
caller. The policy does not resolve symlinks; the call site that performs the effect must
canonicalize and re-check when a symlink could leave the granted tree. net keeps its
caller-defined value shape.
Rejected: substring or prefix matching. It is too coarse for paths and hosts. Rejected: regular expressions. Globs are easier to audit and sufficient for the current boundaries.
clipboard, notification and keychain are not scoped. Grant::new(subject, capability) is
checked with [Policy::check], and Policy::check_scope on an unscoped capability falls back to the
same check. This keeps one call site shape without inventing fake scope values.
Denied carries subject, capability and the value that failed to match, when the check was
scoped. This is enough for a plugin author to fix a manifest without reading framework source.
auro-perms performs no file, network or process I/O. It is a pure policy engine. The call site
that opens the file, connects to the host or spawns the process is the code that asks.
#![allow(unused)] fn main() { pub enum Capability { Fs, Net, Shell, Clipboard, Notification, Keychain, } impl Capability { pub fn as_str(&self) -> &'static str; pub fn is_scoped(&self) -> bool; } pub struct Grant { /* subject, capability, pattern */ } impl Grant { pub fn new(subject: impl Into<String>, capability: Capability) -> Result<Self, PolicyError>; pub fn scoped( subject: impl Into<String>, capability: Capability, pattern: impl Into<String>, ) -> Result<Self, PolicyError>; pub fn subject(&self) -> &str; pub fn capability(&self) -> Capability; pub fn pattern(&self) -> Option<&str>; } pub struct Policy { /* grants */ } impl Policy { pub fn deny_all() -> Self; pub fn allow(self, grant: Grant) -> Self; pub fn allow_scope( self, subject: impl Into<String>, capability: Capability, pattern: impl Into<String>, ) -> Result<Self, PolicyError>; pub fn grants(&self) -> &[Grant]; pub fn check(&self, subject: &str, capability: Capability) -> Result<(), Denied>; pub fn check_scope( &self, subject: &str, capability: Capability, value: &str, ) -> Result<(), Denied>; } }
Errors: PolicyError::InvalidPattern, PolicyError::ScopeRequired,
PolicyError::ScopeNotSupported and UnknownCapability for manifest parsing.
Usage:
let policy = auro::perms::Policy::deny_all()
.allow(
auro::perms::Grant::new("app", auro::perms::Capability::Clipboard)
.expect("unscoped capability"),
)
.allow_scope("plugin:notes", auro::perms::Capability::Fs, "/var/lib/notes/**")?;
policy.check("app", auro::perms::Capability::Clipboard)?;
policy.check_scope("plugin:notes", auro::perms::Capability::Fs, "/var/lib/notes/a.txt")?;
Policy::deny_all() denies every check (denies_by_default).allows_an_unscoped_capability, scopes_are_subject_scoped).matches_a_scoped_grant, rejects_an_out_of_scope_value).capability_strings_round_trip, rejects_an_invalid_pattern, rejects_a_scope_mismatch)../.., and a shell value containing ./..,
are denied before glob matching (rejects_a_traversal_or_relative_filesystem_value).auro::perms re-exports the same API surface (crates/auro/src/lib.rs).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Manifest file format and load path | Plugin host spec |
| Per-window grants for the webview escape hatch | Webview hatch spec |
| Plugin upgrade that widens scopes | Plugin host spec |
| Systemd-style units for scoped shell/notifications | Platform services spec |
Status: Implemented (2026-11-17)
Phase 2 needs apps to be able to opt into launching at login. This spec fixes the autostart service
contract. It delegates the platform mechanics to auto-launch and always uses the
least-privileged Windows mode. The auro::services re-export requires the facade's services
feature.
auro-services::Autostart: enable, disable and query whether an app launches at login.Autostart::new(app_name, app_path, args) and Autostart::for_current_app(app_name, args).auro::services::Autostart re-export.Auro writes the Linux XDG entry itself and delegates the macOS Launch Agent and Windows registry
entry to auto-launch. The platform modes are:
| Platform | Mode | Artifact |
|---|---|---|
| Linux | XdgAutostart | ~/.config/autostart/<app>.desktop |
| macOS | LaunchAgent | ~/Library/LaunchAgents/<app>.plist |
| Windows | CurrentUser | HKCU\...\Run value |
Auro owns the input contract: app_name must be one file-name component (no separators, control
characters or ./..), and app_path must be absolute and exist (a file on Linux). On Linux Auro
also writes the desktop entry itself: $XDG_CONFIG_HOME/autostart when that variable is an absolute
path, otherwise $HOME/.config/autostart, with the executable and every argument quoted for a
Desktop Entry Exec value (% -> %%, backslash/quote/backtick/$ escaping, control characters
rejected). Without that, a path with spaces split into different arguments, a path with %f or a
newline changed the launched command or injected keys, and XDG_CONFIG_HOME was ignored.
macOS and Windows keep delegating to auto-launch. Rejected: AppleScript login items. They need a
macOS GUI session and are less deterministic than a Launch Agent. Rejected: keeping
auto-launch on Linux after its raw Exec interpolation and dirs::home_dir() path proved
unfixable through its public API.
WindowsEnableMode::CurrentUser is used instead of the default Dynamic mode, which would
otherwise try the system registry and require elevation. A user-level app should not ask for admin.
for_current_app resolves the running app and builds the same service as new. On Linux, a
non-empty $APPIMAGE wins over std::env::current_exe(): inside an AppImage the latter points at
the temporary squashfs mount, which disappears when the process exits, so the autostart entry would
launch a missing file at the next login. Elsewhere the path is current_exe(). The app name is
explicit; the path is the running binary.
The service does not fall back to a different mechanism when enable fails. A failed enable is an error the app can surface.
#![allow(unused)] fn main() { pub enum AutostartError { AutoLaunch(auto_launch::Error), // macOS/Windows Invalid { field: &'static str, message: String }, Io(std::io::Error), } pub struct Autostart { /* Linux entry data, or auto_launch::AutoLaunch */ } impl Autostart { pub fn new( app_name: impl Into<String>, app_path: impl Into<String>, args: &[impl AsRef<str>], ) -> Result<Self, AutostartError>; pub fn for_current_app( app_name: impl Into<String>, args: &[impl AsRef<str>], ) -> Result<Self, AutostartError>; pub fn enable(&self) -> Result<(), AutostartError>; pub fn disable(&self) -> Result<(), AutostartError>; pub fn is_enabled(&self) -> Result<bool, AutostartError>; } }
Usage:
let autostart = auro::services::Autostart::for_current_app("com.example.app", &["--quiet"])?;
if !autostart.is_enabled()? {
autostart.enable()?;
}
reports_disabled_by_default).enable and disable round-trip the autostart state
(enables_and_disables_the_service).XDG_CONFIG_HOME and quotes Exec paths/arguments with spaces
(autostart_dir_honors_xdg_config_home, linux_entry_quotes_paths_and_arguments_with_spaces).app_path is rejected
(rejects_a_relative_or_missing_app_path).auro::services re-exports the API surface (crates/auro/src/lib.rs).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| System-wide autostart and admin elevation | Autostart follow-up |
| Custom macOS bundle configuration | Autostart follow-up |
| Scheduling and start conditions | Autostart follow-up |
| Other platform services | Platform services specs |
Status: Implemented (2026-11-17)
Phase 2 needs apps to be able to show desktop notifications. This spec fixes the notification
service contract. The backend is pluggable so tests can record calls instead of firing a real
notification. The auro::services re-export requires the facade's services feature.
auro-services::Notifications: show a desktop notification with title and body.NotificationsBackend: a pluggable backend trait; the default is notify-rust.auro::services::Notifications re-export.notify-rust is the default backendAuro delegates the per-OS mechanics to notify-rust: D-Bus on Linux, NSUserNotificationCenter on
macOS, Windows toast notifications.
Rejected: writing a D-Bus/macOS/Windows client inside Auro. notify-rust is MIT licensed and
already handles the quirks.
Notifications::with_backend accepts any NotificationsBackend. Tests can inject a recorder and
verify the title/body reach the backend without firing a real notification. Production code uses
Notifications::new() and the platform backend.
Rejected: a mock flag on the production type. It keeps the boundary explicit and makes the test double a test-only type.
The service shows a notification and returns; it does not retain a handle to close it later. Click and action callbacks need the app to own the notification lifetime, which is a later slice.
#![allow(unused)] fn main() { pub enum NotificationsError { /* notify_rust::error::Error */ } pub trait NotificationsBackend: Send + Sync { fn show(&self, title: &str, body: &str) -> Result<(), NotificationsError>; } pub struct Notifications { /* backend */ } impl Notifications { pub fn new() -> Self; pub fn with_backend(backend: impl NotificationsBackend + 'static) -> Self; pub fn show(&self, title: impl AsRef<str>, body: impl AsRef<str>) -> Result<(), NotificationsError>; } }
Usage:
let notifications = auro::services::Notifications::new();
notifications.show("Update available", "1.1.0 is ready to install")?;
show sends the title and body to the backend
(sends_the_title_and_body_to_the_backend).NotificationsError
(backend_errors_surface).auro::services re-exports the API surface (crates/auro/src/lib.rs).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Click/action callbacks and closing notifications | Notification UX spec |
| Icons, images, urgency and channels | Notification UX spec |
| Notification categories and quiet hours | Notification UX spec |
| Other platform services | Platform services specs |
Status: Implemented (2026-11-17)
Phase 2 needs apps to be able to persist a secret in the platform keychain. This spec fixes the
keychain service contract. The store is pluggable so tests can use an in-memory backend. The
auro::services re-export requires the facade's services feature.
auro-services::Keychain: set, read and delete one secret.CredentialStore: a pluggable store trait; the default is keyring.auro::services::Keychain re-export.keyring is the default storeAuro delegates the per-OS mechanics to keyring: macOS Keychain Services, Windows Credential
Manager and the Secret Service on Linux.
Rejected: implementing the three stores inside Auro. keyring is MIT/Apache licensed and already
handles the quirks.
Keychain::new(service, username) opens a single entry. The app owns naming; Auro does not enforce
a namespace. This keeps the API small and avoids inventing a policy.
Keychain::with_store accepts any CredentialStore. Tests can inject an in-memory store and
verify the round-trip without touching the real keychain. Production code uses Keychain::new().
Rejected: a mock flag on the production type. It keeps the boundary explicit and makes the test double a test-only type.
KeychainError wraps the platform store error. The caller sees the failure immediately; there is no
retry or fallback inside the service.
#![allow(unused)] fn main() { pub enum KeychainError { /* keyring::Error */ } pub trait CredentialStore: Send + Sync { fn set_password(&self, password: &str) -> Result<(), KeychainError>; fn get_password(&self) -> Result<String, KeychainError>; fn delete_credential(&self) -> Result<(), KeychainError>; } pub struct Keychain { /* store */ } impl Keychain { pub fn new(service: &str, username: &str) -> Result<Self, KeychainError>; pub fn with_store(store: impl CredentialStore + 'static) -> Self; pub fn set_password(&self, password: impl Into<String>) -> Result<(), KeychainError>; pub fn get_password(&self) -> Result<String, KeychainError>; pub fn delete_credential(&self) -> Result<(), KeychainError>; } }
Usage:
let keychain = auro::services::Keychain::new("com.example.app", "api-token")?;
keychain.set_password("hunter2")?;
let password = keychain.get_password()?;
keychain.delete_credential()?;
set_password and get_password round-trip, and delete_credential removes the secret
(round_trips_a_secret).KeychainError
(backend_errors_surface).auro::services re-exports the API surface (crates/auro/src/lib.rs).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Multiple entries and service namespaces | Keychain follow-up |
| Key rotation, expiry and secure memory | Keychain follow-up |
| Platform-specific access controls | Keychain follow-up |
| Other platform services | Platform services specs |
Status: Implemented (2026-11-17; registration and pressed callbacks)
Phase 2 needs apps to be able to register global keyboard shortcuts and react to them. This spec
fixes the shortcut service contract. The backend is pluggable so tests can record calls and invoke
callbacks instead of grabbing an OS-level hotkey. The auro::services re-export requires the
facade's services feature.
auro-services::Shortcuts: register and unregister a global shortcut by string.Shortcuts::on_shortcut: register a callback invoked when that hotkey is pressed.ShortcutBackend: a pluggable backend trait; the default is global-hotkey.auro::services::Shortcuts re-export.global-hotkey.global-hotkey is the default backendAuro delegates the per-OS mechanics to global-hotkey, which uses the Windows registry, X11
grab, and macOS Carbon register hotkey.
Rejected: implementing the three mechanisms inside Auro. global-hotkey is Apache/MIT licensed
and already handles the quirks.
Shortcuts::with_backend accepts any ShortcutBackend. Tests can inject a recorder, verify
register/unregister calls, and fire callbacks without touching OS state. Production code uses
Shortcuts::new().
ShortcutBackend is not Send + Sync, because global-hotkey's Windows manager holds a raw
pointer. The service stores the backend in an Rc, so it is main-thread-only like a GPUI view.
Callbacks are Send + Sync; they run off the app thread.
Rejected: a mock flag on the production type. It keeps the boundary explicit and makes the test
double a test-only type. Rejected: wrapping the manager in a mutex. It would still not be Send
on Windows and would add no useful sharing.
Shortcuts::on_shortcut validates the hotkey and stores the callback keyed by its text. The default
backend maps HotKey::id() to that text at registration time and spawns one auro-shortcuts thread
that reads GlobalHotKeyEvent::receiver(). Pressed events look up the hotkey and invoke every
registered callback; Released events are ignored.
Registration and callback attachment are separate: an app calls register(hotkey) to take the OS
hotkey and on_shortcut(hotkey, callback) to react. This lets an app register before or after the
callback is installed.
The callback runs off the app thread. Apps use EventSender (or another channel) to move the work
onto the main thread; the service does not depend on GPUI or auro-core.
Rejected: polling inside the GPUI event loop. It forces every app to write a timer and a drain loop. Rejected: invoking a GPUI entity from the service. The service would depend on the renderer and the callback would need all the main-thread rules.
#![allow(unused)] fn main() { pub enum ShortcutsError { /* backend, parse, event-loop spawn */ } pub trait ShortcutBackend { fn register(&self, hotkey: &str) -> Result<(), ShortcutsError>; fn unregister(&self, hotkey: &str) -> Result<(), ShortcutsError>; fn on_shortcut( &self, hotkey: &str, handler: Arc<dyn Fn() + Send + Sync>, ); } pub struct Shortcuts { /* backend */ } impl Shortcuts { pub fn new() -> Result<Self, ShortcutsError>; pub fn with_backend(backend: impl ShortcutBackend + 'static) -> Self; pub fn register(&self, hotkey: &str) -> Result<(), ShortcutsError>; pub fn unregister(&self, hotkey: &str) -> Result<(), ShortcutsError>; pub fn on_shortcut<F>(&self, hotkey: &str, handler: F) -> Result<(), ShortcutsError> where F: Fn() + Send + Sync + 'static; } }
Usage:
let shortcuts = auro::services::Shortcuts::new()?;
shortcuts.on_shortcut("shift+alt+k", move || {
// Send to the app thread.
})?;
shortcuts.register("shift+alt+k")?;
shortcuts.unregister("shift+alt+k")?;
register and unregister call the backend with the hotkey
(registers_and_unregisters_the_hotkey).dispatches_a_pressed_hotkey).rejects_an_invalid_callback_hotkey).ShortcutsError (backend_errors_surface).rejects_an_invalid_hotkey).auro::services re-exports the API surface (crates/auro/src/lib.rs).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Persisting shortcuts across restarts | Shortcut UX spec |
| Custom key parsing | Shortcut UX spec |
| Release events and repeat suppression | Shortcut UX spec |
| Other platform services | Platform services specs |
Status: Implemented (2026-11-18; icon selection, menu and click callbacks)
Phase 2 needs apps to be able to show a system tray icon with a small menu and react to clicks. This
spec fixes the tray service contract. The backend is pluggable so tests can inspect visibility,
tooltip and menu changes and fire events instead of creating a real tray icon. The
auro::services re-export requires the facade's services feature, and Tray additionally
requires the tray feature. On Linux the backend speaks StatusNotifierItem over D-Bus; it needs no
GTK initialization and no GTK event loop, which an app built on GPUI cannot provide.
auro-services::Tray: show or hide a tray icon, set its tooltip and supply RGBA pixels.TrayIcon: validated RGBA pixels and dimensions.TrayMenuItem and Tray::set_menu: replace the context menu.Tray::on_menu_event: receive the activated item's id.TrayClick, TrayButton, TrayButtonState and Tray::on_click: receive icon clicks.TrayBackend: a pluggable backend trait; the default is tray-icon.auro::services::Tray re-export.tray-icon is the default backendAuro delegates the per-OS mechanics to tray-icon, which uses the Windows shell, macOS
NSStatusItem and, on Linux, the StatusNotifierItem D-Bus protocol through its ksni backend. The
ksni backend runs its own D-Bus thread, so Tray::new() works before any GTK or GPUI loop exists
and does not need the application to pump a GTK loop.
Rejected: implementing the three mechanisms inside Auro. tray-icon is MIT licensed and already
handles the quirks. Rejected: tray-icon's AppIndicator backend, which requires gtk::init on a
thread that must also run the GTK main loop; a GPUI app owns its main thread and cannot provide
that loop without a second event loop.
Tray::with_backend accepts any TrayBackend. Tests can inject a recorder and verify show/hide,
tooltip and menu changes, then invoke the stored callbacks without creating a real tray icon.
Production code uses Tray::new().
TrayBackend is not Send + Sync, because tray-icon's internal handle is not Send. The
service stores the backend in an Arc, but the trait object is main-thread-only like a GPUI view.
Callbacks are Send + Sync; they run off the app thread.
Rejected: a mock flag on the production type. It keeps the boundary explicit and makes the test double a test-only type.
TrayMenuItem is a flat id/label/enabled item. Tray::set_menu rebuilds and installs a platform
menu; Tray::on_menu_event receives the activated id. Tray::on_click receives a TrayClick with
the button and up/down state; enter/move/leave/double-click events are ignored. TrayIcon carries
validated RGBA pixels; Tray::set_icon replaces or clears the icon.
The callback runs off the app thread. Apps use EventSender (or another channel) to move the work
onto the main thread; the service does not depend on GPUI or auro-core.
The platform event handlers are process-global and can only be installed once per process. The
service documents this; a second on_menu_event or on_click call is intentionally not supported.
On Linux, StatusNotifierItem delivers the primary activation as a left-button Up click and the
secondary activation as a middle-button Up click; right-click is owned by the status-notifier
host, which opens the menu. Menus and icons can be replaced after creation.
Rejected: a per-tray event dispatcher thread. tray-icon already owns the platform event source;
an extra thread would only copy events and complicate shutdown.
#![allow(unused)] fn main() { pub enum TrayError { /* tray_icon, menu or icon error */ } pub struct TrayIcon { /* rgba, width, height */ } impl TrayIcon { pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, TrayError>; pub fn width(&self) -> u32; pub fn height(&self) -> u32; pub fn rgba(&self) -> &[u8]; } pub struct TrayMenuItem { pub id: String, pub label: String, pub enabled: bool, } pub enum TrayButton { Left, Right, Middle } pub enum TrayButtonState { Up, Down } pub struct TrayClick { pub button: TrayButton, pub state: TrayButtonState, } pub trait TrayBackend { fn set_visible(&self, visible: bool) -> Result<(), TrayError>; fn set_tooltip(&self, tooltip: Option<String>) -> Result<(), TrayError>; fn is_visible(&self) -> bool; fn set_icon(&self, icon: Option<TrayIcon>) -> Result<(), TrayError>; fn set_menu(&self, items: Vec<TrayMenuItem>) -> Result<(), TrayError>; fn set_menu_event_handler(&self, handler: Arc<dyn Fn(&str) + Send + Sync>); fn set_click_event_handler(&self, handler: Arc<dyn Fn(TrayClick) + Send + Sync>); } pub struct Tray { /* backend */ } impl Tray { pub fn new() -> Result<Self, TrayError>; pub fn with_backend(backend: impl TrayBackend + 'static) -> Self; pub fn set_visible(&self, visible: bool) -> Result<(), TrayError>; pub fn set_tooltip(&self, tooltip: Option<String>) -> Result<(), TrayError>; pub fn is_visible(&self) -> bool; pub fn set_icon(&self, icon: Option<TrayIcon>) -> Result<(), TrayError>; pub fn set_menu(&self, items: &[TrayMenuItem]) -> Result<(), TrayError>; pub fn on_menu_event<F>(&self, handler: F) where F: Fn(&str) + Send + Sync + 'static; pub fn on_click<F>(&self, handler: F) where F: Fn(TrayClick) + Send + Sync + 'static; } }
Usage:
let tray = auro::services::Tray::new()?;
tray.set_menu(&[
auro::services::TrayMenuItem::new("show", "Show"),
auro::services::TrayMenuItem::new("quit", "Quit"),
])?;
tray.on_menu_event(|id| {
// Send `id` to the app thread.
});
tray.set_visible(true)?;
set_visible toggles the backend and is reflected by is_visible
(shows_and_hides_the_icon).set_tooltip passes the tooltip to the backend and can clear it
(updates_the_tooltip).sets_and_clears_the_icon).set_menu passes the items to the backend and menu events reach the callback
(sets_a_menu_and_dispatches_its_events).dispatches_clicks).TrayError (backend_errors_surface).auro::services re-exports the API surface (crates/auro/src/lib.rs).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, cargo test -p auro-services --features tray --locked,
cargo check -p auro --features services,tray --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| PNG/theme icon decoding | Tray UX spec |
| Tray persistence across restarts | Tray UX spec |
| Submenus, check items and accelerators | Tray UX spec |
| Other platform services | Platform services specs |
Status: Implemented (2026-11-18; initial and forwarded arguments are wired; macOS bundle registration is packager-owned)
Phase 2 needs apps to accept URL-scheme launches. This spec fixes the deep-link service contract:
scheme validation, registration, parsing and a queue that waits for the app. The auro::services
re-export requires the facade's services feature.
auro-services::register_scheme: register a scheme for the current user.auro-services::AppLinks: parse accepted schemes and queue links until drained.DeepLink: scheme, host, decoded segments, decoded query and raw argument.auro::services::AppLinks and register_scheme re-exports.App::deep_links(links): queues initial process arguments and forwarded InstanceMessage
arguments into a shared queue.CFBundleURLTypes editing; the packager owns the bundle's Info.plist..desktop installation by the packager; the service writes a user entry and calls
xdg-mime.AppLinks::new takes the accepted schemes. parse rejects any other scheme, control characters,
links over 4096 bytes, empty hosts and ./.. path segments. The app sees only links it asked for.
register_scheme validates the RFC 3986 grammar: the first character is ASCII alphabetic and the
rest are ASCII alphanumerics or +, -, .. A leading digit and _ are rejected; + is accepted.
register_scheme always acts in the current user's namespace:
| Platform | Mechanism |
|---|---|
| Windows | HKCU\Software\Classes\<scheme> via reg.exe |
| Linux | XDG desktop entry plus xdg-mime default |
| macOS | packager's CFBundleURLTypes; the call is a no-op |
The Linux entry's Exec value quotes the executable and escapes it for the Desktop Entry spec:
% -> %% (field codes expand even inside quotes), "/\/`/$ are escaped, and control
characters (including \n) are rejected so a path cannot inject another key.
Rejected: writing machine-wide registry keys or system desktop files. They need elevation and are not appropriate for an app-level link.
Links arrive from launch arguments and may arrive before the UI is ready. AppLinks stores parsed
links in a mutex-protected FIFO and returns them in arrival order on drain. Callers can ignore
duplicates themselves; the queue does not deduplicate.
Percent decoding is UTF-8-aware. Control characters are rejected after decoding. Path traversal is rejected before the app sees a segment. Invalid links are dropped, not turned into partial links.
Rejected: handing raw strings to every app. Every consumer would re-implement the same checks.
#![allow(unused)] fn main() { pub enum DeepLinkError { Register(String), InvalidScheme(String) } pub struct DeepLink { pub scheme: String, pub host: String, pub segments: Vec<String>, pub query: BTreeMap<String, String>, pub raw: String, } pub fn register_scheme( scheme: &str, executable: &std::path::Path, ) -> Result<(), DeepLinkError>; pub struct AppLinks { /* queue, schemes */ } impl AppLinks { pub fn new(schemes: Vec<String>) -> Self; pub fn push(&self, raw: &str); pub fn push_raw(&self, raw: &[String]); pub fn drain(&self) -> Vec<DeepLink>; pub fn schemes(&self) -> &[String]; } impl App { #[cfg(feature = "services")] pub fn deep_links(self, links: AppLinks) -> Self; } }
Usage:
let links = auro::services::AppLinks::new(vec!["myapp".to_owned()]);
App::new()
.deep_links(links.clone())
.single_instance()
.root::<View>("main")
.run();
for link in links.drain() {
// route `link.host`, `link.segments`, `link.query`
}
scheme://host/path?key=value parses into scheme, host, segments and query
(parses_a_deep_link).rejects_an_unknown_scheme,
rejects_a_traversal_path).rejects_an_empty_or_bad_scheme).AppLinks handles share one FIFO (clones_share_the_same_queue); App::deep_links
stores that shared handle behind the services feature and the run path feeds initial and
forwarded InstanceMessage arguments.auro::services re-exports the API surface (crates/auro/src/lib.rs).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Universal links / HTTPS associations | Deep-link follow-up |
| macOS bundle registration automation | Packager follow-up |
| Unknown-origin consent policy | Deep-link UX spec |
Status: Implemented (2026-11-17; keyboard activation only; AccessKit and IME audit pending)
Phase 2 needs keyboard-operable controls. This spec fixes the first slice: the primitive Button
participates in the tab order and activates from the keyboard. It does not claim a full
accessibility pass.
auro_ui::Button is focusable and a tab stop.Button renders with focusable().tab_stop(true).tab_index(0). GPUI stores a focus handle in the
element state, so Auro does not need a second, app-owned handle for this primitive.
The keyboard handler calls the existing on_click handler with ClickEvent::default() (the
keyboard variant). A control has one activation path, not two subtly different ones.
Rejected: a separate on_activate callback. It doubles the API surface before there is a second
control that needs it.
Only unmodified Enter/Space activates. A held key does not fire repeatedly; key repeat is not a click. Modal shortcuts belong to the app's key bindings, not to the primitive.
#![allow(unused)] fn main() { pub struct Button { /* id, label, on_click */ } impl Button { pub fn new(id: impl Into<SharedString>, label: impl Into<SharedString>) -> Self; pub fn on_click( self, handler: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static, ) -> Self; } }
Behavior: after the button is focused (for example with Tab), Enter or Space invokes on_click.
button_activates_with_enter_and_space).clicking_button_dispatches_async_command_and_updates_view).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| AccessKit tree and screen-reader parity | Upstream GPUI / accessibility spec |
| IME and composition behavior | Platform input audit |
| Focus-ring styling and tokens | Design-system follow-up |
| Full tab order across primitives | Accessibility follow-up |
Status: Implemented (2026-11-18 for v0.1.0-alpha.1; 2026-11-19 for v0.1.0-alpha.2;
2026-11-20 for v0.1.0-alpha.3 and v0.1.0-alpha.4; 2026-11-21 for v0.1.0-alpha.5,
v0.1.0-alpha.6 and v0.1.0-alpha.7). All eleven crates are published; final README copy and
screenshots remain follow-ups.
The first public alpha publishes the workspace crates as 0.1.0-alpha.1. This spec collects the
release contract that is not owned by an earlier feature spec: versioning, publish order, crate
metadata, facade features, and the scaffold's dependency mode.
0.1.0-alpha.1.publish = ["crates-io"] only in the release commit.auro new emits a path dependency inside this checkout and a version dependency when the CLI is
installed from crates.io.The first public version is 0.1.0-alpha.1 for every crate. The workspace version and every
internal dependency version move together; a workspace-local skew is a bug. 0.0.0 is a build
placeholder and is never published. 0.1.0-alpha.2 follows the same rule for the second alpha.
crates.io resolves dependencies from the registry, not from path dependencies. Publication order:
auro-macros, auro-ipc, auro-sign, auro-perms, auro-servicesauro-coreauro-updateauro-uiauro-bundleauroauro-cliThe first five fit the new-crate burst; the remaining six are spaced by the crates.io limit of one new crate per ten minutes. Each crate is dry-run and verified before the next.
auro-services keeps its OS integrations separate. The facade features are:
[features]
services = ["dep:auro-services"]
tray = ["services", "auro-services/tray"]
services is off by default. tray is off by default even when services are enabled, because it
adds a D-Bus status-notifier backend and platform event handlers to apps that do not need them.
Users who need a tray enable tray explicitly.
auro new cannot know at build time whether it runs from this checkout or from crates.io. It emits
a path dependency when ../crates/auro exists relative to the CLI manifest, and otherwise emits
the CLI's own CARGO_PKG_VERSION string. The in-repo path keeps development against the checkout;
the registry version keeps an installed CLI's generated app buildable.
Every crate carries a description, licence, repository, homepage, README, keywords and categories.
The README is inside the crate root so Cargo includes it in the tarball. Licence files are included
or referenced from the package. cargo package --list and cargo publish --dry-run are the
verification steps.
publish = false stays in the workspace until the release commit. The release commit changes it to
["crates-io"] and carries the version bump in the same change. Publishing is never part of an
ordinary feature PR.
cargo metadata reports 0.1.0-alpha.1 for every crate and no path-only internal dependency
lacking a registry version.cargo package -p <leaf> succeeds for each leaf crate, and cargo publish --dry-run -p <leaf>
succeeds after the release switch.cargo tree -p auro -e normal contains no tray-icon in the default feature set;
--features services adds the service crates; --features tray adds tray-icon. No feature
set pulls GTK or libappindicator.cargo test -p auro-cli covers the in-repo path and installed-version scaffold modes.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.0.1.0-alpha.1; auro --version
reports it.auro features services and tray are in place; default cargo tree -p auro contains no
tray-icon, and no feature set pulls GTK or libappindicator.auro new emits the workspace path in this checkout and the CLI's version when installed from a
registry; both modes are tested.cargo package includes
the README.auro-macros, auro-ipc, auro-sign, auro-perms and auro-services package and verify.
auro-perms completed cargo publish --dry-run with the release switch locally enabled.v0.1.0-alpha.1 points at ac4d996 (the merge of the release-preparation changes).0.1.0-alpha.1 as their maximum published version on crates.io:
auro-macros, auro-ipc, auro-sign, auro-perms, auro-services, auro-core,
auro-update, auro-ui, auro-bundle, auro, auro-cli.0.1.0-alpha.20.1.0-alpha.2; all eleven crates report it as
their maximum published version on crates.io.AuroError::Platform) and the Windows journal ancestor validation.v0.1.0-alpha.2 points at the release commit.0.1.0-alpha.30.1.0-alpha.3; all eleven crates report it as
their maximum published version on crates.io.v0.1.0-alpha.3 points at the release commit.0.1.0-alpha.40.1.0-alpha.4; all eleven crates report it as
their maximum published version on crates.io.v0.1.0-alpha.4 points at the release commit.0.1.0-alpha.50.1.0-alpha.5; all eleven crates report it as
their maximum published version on crates.io.v0.1.0-alpha.5 points at the release commit.0.1.0-alpha.60.1.0-alpha.6; all eleven crates report it as
their maximum published version on crates.io.v0.1.0-alpha.6 points at the release commit.0.1.0-alpha.70.1.0-alpha.7; all eleven crates report it as
their maximum published version on crates.io.v0.1.0-alpha.7 points at the release commit.| Question | Where it settles |
|---|---|
| Final README copy and screenshots | Release follow-up |
Whether auro-perms is also feature-gated | Alpha follow-up |
Whether auro keeps a default service feature | Alpha follow-up |
| Long-term release automation/trusted publishing | Release engineering follow-up |
Status: Implemented (2026-11-17; Windows MSI/NSIS execution and macOS .app.zip replacement;
.dmg, notarization and package elevation are separate; macOS .pkg apply is spec 0031, Linux package elevation is spec 0029; restart handoff is spec 0026)
Spec 0013 stops at a verified staged artifact. Spec 0014 adds the Linux AppImage apply path. This
spec adds the next two platform paths: run a Windows MSI/NSIS installer, and replace a macOS .app
bundle from a staged .zip. Both consume a [StagedUpdate], so the manifest signature, artifact
size and SHA-256 were checked before any platform action.
auro-update::WindowsInstaller: detect .msi/.exe, run the installer silently, and classify
exit codes 0, 3010 and 1641.InstallerRunner: the command boundary, injectable for tests; no shell.auro-update::MacAppInstaller: extract a .zip containing exactly one top-level .app, swap it
over an existing bundle, and return a rollback receipt.MacAppReceipt: report the installed bundle and backup, roll back, or discard.updater feature, gated by the host OS.sudo, admin prompts or a privileged helper process..dmg mounting, notarization and Apple package-signature policy; .pkg apply is
spec 0031..deb/.rpm package-manager apply.WindowsInstaller inspects the staged artifact extension:
| Format | Program | Arguments |
|---|---|---|
.msi | %SystemRoot%\System32\msiexec.exe | /i <artifact> /qn /norestart |
.exe | <artifact> | /S (assumed NSIS) |
InstallerRunner receives an argument vector and uses std::process::Command directly. MSI uses
%SystemRoot%\System32\msiexec.exe, not a PATH lookup. The service does not build a command string,
so a path cannot inject shell syntax. A missing artifact is StagedArtifactMissing; an unknown
extension is UnsupportedInstaller.
Exit code 0 succeeds. 3010 (reboot required) and 1641 (reboot initiated) succeed with
restart_required: true. Every other code, including a terminated process with no code, is
InstallerFailed. The app decides when to restart; run the installer off the UI thread.
Rejected: a generic "run this command" hook. It moves platform policy into app code and makes
the silent flags, exit-code mapping and test boundary invisible. Rejected: downloading the
installer again here; only the verified StagedUpdate is accepted.
.app directory from a zipMacAppInstaller accepts a staged .zip with exactly one top-level .app. It extracts with
zip's enclosed-path extractor and then walks the extracted tree, rejecting any symlink whose
canonical target escapes the extraction directory. Nested symlinks are allowed when they stay
inside the bundle. It renames the old bundle to a hidden backup beside it, renames the new bundle
into place, and returns MacAppReceipt.
The extraction directory is created beside the target, so the final rename stays on one filesystem.
If the new rename fails, the backup is renamed back. The receipt follows the conservative
AppImage rule: dropping it keeps the backup; the app calls discard after verifying the new
version or rollback to restore the old bundle. Rollback removes the installed bundle first because
a directory rename cannot replace a non-empty directory.
Release tooling must preserve executable modes and symlinks in the .app.zip; ditto -c -k on
macOS is the reference packaging command. The zip dependency enables the deflate codec only, so
artifacts using zstd/deflate64 fail with Archive.
Rejected: applying a .dmg by mounting it and copying. That needs hdiutil, mount parsing,
detach handling and a helper/privilege story. A zip is a deterministic file format with a safe
extractor and a straightforward test path. Rejected: replacing files inside the bundle in place;
it cannot be atomic and leaves mixed versions after a crash.
InstallerRunner is public and returns the exit code or None. Production uses
SystemInstallerRunner; tests inject a recorder and inspect the exact program and argument vector
without launching an installer. Windows command construction and macOS bundle replacement are
therefore tested on Linux CI, while the host-specific types remain exported only on their host.
Rejected: #[cfg(test)] branches inside the production install function. The runner keeps the
test double explicit and lets an app provide a custom runner if needed.
A Windows installer may return 3010 or 1641, and a macOS bundle is used on the next launch.
Neither
installer waits for the current process, relaunches the app, or requests elevation. Those are a
separate restart/helper contract; claiming them here would be false.
#![allow(unused)] fn main() { pub trait InstallerRunner { fn run(&self, program: &Path, args: &[OsString]) -> Result<Option<i32>, UpdateError>; } pub struct SystemInstallerRunner; pub enum WindowsInstallerKind { Msi, Nsis } pub struct WindowsInstallOutcome { pub kind: WindowsInstallerKind, pub restart_required: bool, } pub struct WindowsInstaller { /* runner */ } impl WindowsInstaller { pub fn new() -> Self; pub fn with_runner(runner: impl InstallerRunner + 'static) -> Self; pub fn install( &self, staged: &StagedUpdate, ) -> Result<WindowsInstallOutcome, UpdateError>; } pub struct MacAppInstaller { /* target */ } impl MacAppInstaller { pub fn new(target: impl Into<PathBuf>) -> Self; pub fn target(&self) -> &Path; pub fn install(&self, staged: &StagedUpdate) -> Result<MacAppReceipt, UpdateError>; } pub struct MacAppReceipt { /* target, backup */ } impl MacAppReceipt { pub fn target(&self) -> &Path; pub fn backup(&self) -> &Path; pub fn rollback(self) -> Result<(), UpdateError>; pub fn discard(self) -> Result<(), UpdateError>; } }
WindowsInstaller is re-exported on Windows, and MacAppInstaller/MacAppReceipt on macOS. Both
are unit-tested on Linux through cfg(test).
Errors added to UpdateError: InstallTargetNotDirectory, UnsupportedInstaller,
InstallerFailed, AppBundleMissing, AppBundleAmbiguous, Archive, UnsafeArchive,
RestoreFailed and RollbackFailed.
Usage:
let staged = updater.download(&manifest)?;
#[cfg(target_os = "windows")]
let outcome = auro::update::WindowsInstaller::new().install(&staged)?;
#[cfg(target_os = "macos")]
let receipt = auro::update::MacAppInstaller::new("/Applications/Demo.app").install(&staged)?;
The snippet is an intended call shape, not an app that exists yet.
msiexec with /i, the staged path, /qn and /norestart
(runs_msi_installer_silently)..exe with /S (runs_nsis_installer_silently).3010/1641 report restart_required; another code is InstallerFailed and keeps the code
(maps_reboot_required_and_failure).UnsupportedInstaller (rejects_unknown_artifacts)..app.zip replaces the bundle, retains the old bundle in the receipt, and rollback restores
the old contents (installs_and_rolls_back_an_app_bundle).discard removes the backup (discards_the_backup_after_success)..app fails with AppBundleMissing and leaves the target unchanged
(rejects_an_archive_without_an_app_bundle)..dmg staged artifact is rejected as unsupported (rejects_an_unsupported_archive).UnsafeArchive (rejects_symlinks_escaping_the_bundle), while an in-bundle symlink is allowed
(allows_symlinks_inside_the_bundle)..app bundles is rejected without touching the target
(rejects_an_ambiguous_archive).InstallTargetMissing/
InstallTargetNotDirectory, and a corrupt zip fails with Archive before touching the target
(rejects_missing_or_non_directory_targets, corrupt_archive_leaves_the_target_untouched).StagedArtifactMissing
(reports_a_missing_staged_artifact, macOS rejects_a_missing_staged_artifact), a terminated
Windows installer is InstallerFailed { code: None } (reports_a_terminated_installer), and a
macOS rollback with a missing backup reports RollbackBackupMissing
(rollback_reports_a_missing_backup).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, cargo test -p auro-update --locked,
cargo check -p auro --features updater --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Windows elevation, reboot and installer UI policy | Windows update UX/spec |
macOS .dmg apply | macOS disk-image apply spec |
macOS .pkg apply | macOS package apply |
.deb/.rpm package-manager apply | Linux package apply, elevation |
| Restart/helper protocol and crash-safe apply journal | Update journal and restart helper |
| macOS code-signing preservation and notarization checks | macOS notarization |
| Automatic downgrade policy | Linux package rollback |
Status: Implemented (2026-11-18; journal, helper-side apply/relaunch, reconciliation and cleanup;
automatic startup recovery, elevation (spec 0029) and helper-side .dmg apply are separate)
Spec 0025 stops after the platform apply. A running app still needs to record what it installed, hand off after it exits, and relaunch the replacement. This spec fixes that handoff.
auro-update::ApplyJournal: a durable, atomically written JSON record for one apply attempt.ApplyKind: None, AppImage, WindowsInstaller, MacApp, MacPkg, DebPackage, RpmPackage.Prepared, Applied, RebootRequired, Failed, RolledBack, Restarted..deb/.rpm in the journal; the helper reinstalls it when the
primary package apply fails with InstallerFailed (spec 0030).Relaunch: executable, arguments and working directory for the replacement process.ApplyJournal::spawn_helper: locks the exit handoff and starts the same executable in helper
mode.ApplyJournal::reconcile: classifies the next-start action from state and running version.ApplyJournal::finalize: removes the retained backup, journal and lock after Complete.App::try_run helper bootstrap: when RESTART_HELPER_ENV is set, wait for the old process to
release the lock and relaunch without starting GPUI.updater feature..dmg, .deb/.rpm automatic rollback and signed macOS helper policy; .pkg apply is
spec 0031.sudo or Auro-managed passwords.reconcile/finalize into every app startup; the app calls them.The journal is a small JSON file (format version 2) written with a sibling temporary file,
sync_all, and an atomic rename. It stores the format version, release version, artifact path,
optional target and backup, state, diagnostic message, relaunch command and lock path. The reader
checks format before decoding the full schema, so an older journal is a typed JournalFormat
rather than a missing-field JSON error.
Every state transition is written through with a sibling temporary file, sync_all and rename;
parent-directory sync is not performed. The journal has no implicit default state on load: a
missing, malformed or unknown-format file, or a lock path that is not the journal's sibling, is a
typed error. This makes a crash visible instead of turning it into a fresh update.
Rejected: an in-memory receipt. A process that exits for an update cannot report what it was doing. Rejected: using the journal itself as the lock; atomic replacement changes the inode.
spawn_helper opens a sibling lock file, takes an exclusive lock, and spawns
std::env::current_exe() with AURO_UPDATE_RESTART_HELPER=<journal>. App::try_run sees that
variable before loading config or starting GPUI and calls run_restart_helper.
The lock handle is retained in a process-global guard. The helper checks Applied before opening
the lock, then polls until the running app exits (120 s timeout), reloads the journal, and requires
Applied again; anything else is a typed JournalNotApplied. The lock path must be the journal's
sibling, and the relaunch executable must exist before spawning.
This keeps a single artifact to bundle and works for AppImage, Windows installers and macOS apps,
including when the old executable path is replaced while the helper process is still running. On
Linux, Relaunch::current uses $APPIMAGE because current_exe() points at the temporary squashfs
mount, which disappears when the old process exits. The helper is re-executed from the executable
path as it exists after apply; the new build must honor the same environment/journal contract.
Rejected: a separate helper crate/binary and packaging convention. It adds a second build artifact
and a discovery problem before the handoff is proven. Rejected: a shell loop or cmd /C waiting
for a PID. It builds commands from paths and behaves differently per platform.
A Prepared journal may carry an ApplyKind, the staged manifest and the app-provided public key.
create_for_apply runs the same preflight while the app is still alive: the apply kind must be
supported on this host; an AppImage target must be an existing file and a macOS .app target an
existing directory; the artifact must exist, verify against the manifest signature, size and
SHA-256, and match the kind's format (.msi/.exe, .deb, .rpm, .zip for MacApp, .pkg;
an AppImage has no required extension); the manifest version/platform must match the journal and
host; a package rollback must match the same kind; and a .deb/.rpm apply requires
/usr/bin/pkexec plus /usr/bin/dpkg or /usr/bin/rpm. A bad plan is rejected before the process
handoff; otherwise the helper would reject it after the app exits and never relaunch. The helper
repeats every check (defense in depth), then records a retained backup for AppImage/macOS, marks
the journal Applied,
and only then relaunches. An Applied journal with ApplyKind::None keeps the
synchronous-apply behavior: the helper just relaunches. A Windows installer that returns
3010/1641 leaves the journal RebootRequired and does not relaunch the old binary as if the
update were complete.
If apply fails, the helper marks the journal Failed with the diagnostic, leaves the journal for
inspection and does not relaunch. If the journal is neither Prepared with an apply kind nor
Applied, the helper refuses to launch anything. Because the helper's stdio is detached, it also
records any later relaunch/lock failure into the journal before returning.
Rejected: a second platform-apply implementation inside the helper. The helper reuses the same
AppImageInstaller, WindowsInstaller and MacAppInstaller code. Rejected: automatic elevation.
It is still a separate privilege/contract problem.
finalize removes the journal before the backup. If the journal cannot be removed (read-only
directory, permission error), the backup it names is still the rollback copy and must survive; an
orphaned backup after a successful journal removal is preferable to a journal pointing at a deleted
recovery file.
The helper process is started in its own process group (Unix process_group(0), Windows
CREATE_NEW_PROCESS_GROUP) so a terminal process-group signal does not kill the handoff. The
relaunched process is spawned with RESTART_HELPER_ENV removed, standard streams null, the
journal's working directory and arguments. The helper records Restarted after a successful spawn
and exits. It never builds a shell command.
The journal is intentionally left on disk for diagnosis. Cleanup is the app's or a future recovery policy's job.
The journal carries the verification key, staged artifact path, platform target and the relaunch
program and arguments. The helper trusts all of them; re-verifying the artifact with the key the
journal names proves internal consistency, not who wrote the file. The journal and its lock must
therefore live in a directory only the current user can write (for example the app's data
directory), and the caller must not point ApplyJournal or RESTART_HELPER_ENV at a shared
location. A journal planted by another local user would otherwise be able to name its own key,
artifact and relaunch executable, and a package apply would reach the elevation prompt with that
caller-supplied package.
Auro enforces the journal boundary in ApplyJournal::load, save and the helper's lock open
(spec 0033). Unix opens the journal, lock and directories without
following symlinks, requires the file and immediate directory to be owned by the effective user,
refuses group/other write bits, and rejects an ancestor that another user can write (root-owned
sticky ancestors such as /tmp are allowed only as ancestors). Windows opens reparse points
themselves, rejects the reparse attribute, and requires the owner and every write/delete/ACL ACE to
belong to the current user, SYSTEM, Administrators or the creator-owner SIDs. A path that
cannot be proven private is UpdateError::JournalTrust; there is no public bypass.
The Windows tests run on GitHub Actions windows-latest and pass (private directory, junction,
permissive DACL and symlink), but the Windows path does not walk ancestors; a shared ancestor that
can rename the private directory remains a gap. The staging directory and verify-then-open handoff
to an external installer remain open (RFC 0001). The helper never self-elevates; the elevation
prompt and the package manager remain the user's decision (spec 0029).
#![allow(unused)] fn main() { pub const RESTART_HELPER_ENV: &str = "AURO_UPDATE_RESTART_HELPER"; pub enum ApplyKind { None, AppImage, WindowsInstaller, MacApp, MacPkg, } pub enum ApplyState { Prepared, Applied, RebootRequired, Failed, RolledBack, Restarted, } pub struct ApplyPlan { pub kind: ApplyKind, pub artifact: PathBuf, pub target: Option<PathBuf>, pub manifest: Manifest, pub public_key: PublicKey, pub rollback: Option<PackageRollback>, } impl ApplyPlan { pub fn new( kind: ApplyKind, artifact: impl Into<PathBuf>, target: Option<PathBuf>, manifest: Manifest, public_key: PublicKey, ) -> Self; pub fn with_package_rollback(self, rollback: PackageRollback) -> Self; } pub struct Relaunch { pub program: PathBuf, pub args: Vec<String>, pub cwd: PathBuf, } impl Relaunch { pub fn current() -> Result<Self, UpdateError>; } pub enum Recovery { RetryApply, Prepared, Complete, Relaunch, AwaitReboot, Failed, RolledBack, } pub struct ApplyJournal { /* path, data */ } impl ApplyJournal { pub fn create( path: impl Into<PathBuf>, version: impl Into<String>, artifact: impl Into<PathBuf>, target: Option<PathBuf>, relaunch: Relaunch, ) -> Result<Self, UpdateError>; pub fn create_for_apply( path: impl Into<PathBuf>, version: impl Into<String>, plan: ApplyPlan, relaunch: Relaunch, ) -> Result<Self, UpdateError>; pub fn load(path: impl Into<PathBuf>) -> Result<Self, UpdateError>; pub fn path(&self) -> &Path; pub fn state(&self) -> ApplyState; pub fn backup(&self) -> Option<&Path>; pub fn rollback_artifact(&self) -> Option<&Path>; pub fn set_backup(&mut self, backup: impl Into<PathBuf>) -> Result<(), UpdateError>; pub fn reconcile(&self, current_version: &str) -> Result<Recovery, UpdateError>; pub fn finalize(self) -> Result<(), UpdateError>; pub fn mark_applied(&mut self) -> Result<(), UpdateError>; pub fn mark_failed(&mut self, message: impl Into<String>) -> Result<(), UpdateError>; pub fn mark_rolled_back(&mut self) -> Result<(), UpdateError>; pub fn mark_reboot_required(&mut self) -> Result<(), UpdateError>; pub fn mark_restarted(&mut self) -> Result<(), UpdateError>; pub fn record_message(&mut self, message: impl Into<String>) -> Result<(), UpdateError>; pub fn spawn_helper(&self) -> Result<(), UpdateError>; pub fn remove(self) -> Result<(), UpdateError>; } pub fn run_restart_helper(path: &Path) -> Result<(), UpdateError>; }
Errors added to UpdateError: JournalMissing, JournalFormat, JournalNotApplied,
JournalLockPath, RelaunchMissing, ApplyKindMissing, ManifestMissing,
ApplyTargetMissing, UnsupportedApply, VerificationKeyMissing, JournalVersionMismatch,
JournalPlatformMismatch, JournalBackupPath, JournalBackupTargetMissing, RestartLock and
RestartTimeout.
Usage:
let journal = auro::update::ApplyJournal::create_for_apply(
state_dir.join("apply.json"),
manifest.version.clone(),
auro::update::ApplyPlan::new(
auro::update::ApplyKind::AppImage,
staged.path().to_path_buf(),
Some(target.clone()),
manifest.clone(),
updater.public_key(),
),
auro::update::Relaunch::current()?,
)?;
journal.spawn_helper()?;
cx.quit();
// The helper applies the staged artifact and relaunches after this process exits.
The snippet is an intended call shape, not an app that exists yet. The app must hold the journal
until spawn_helper returns; the lock is retained by the helper module.
round_trips_state_through_disk).rejects_a_missing_or_unknown_journal).spawn_helper refuses a non-Applied journal and a held lock (refuses_to_spawn_before_apply,
refuses_to_spawn_when_the_lock_is_held), and spawns a helper with the journal path in
AURO_UPDATE_RESTART_HELPER (spawns_a_helper_with_the_journal_path).run_restart_helper launches the configured command, marks Restarted, and leaves the journal
readable (helper_relaunches_and_marks_the_journal); on Linux it honors $APPIMAGE
(uses_the_appimage_path_for_relaunch). A prepared AppImage plan is verified and applied before
relaunch, with its backup retained (helper_applies_an_appimage_before_relaunch); a tampered
artifact is rejected (helper_rejects_a_tampered_staged_artifact), a version/platform mismatch
is rejected before apply (helper_rejects_a_manifest_version_mismatch,
helper_rejects_a_manifest_platform_mismatch), an unsupported kind marks Failed
(helper_marks_an_unsupported_apply_failed), and a reboot request is recorded
(records_reboot_state).helper_rejects_an_unapplied_journal, helper_refuses_a_state_flipped_while_waiting).reconcile classifies prepared/applied/current/failed states; finalize removes a sibling
backup, journal and lock, while refusing an unrelated backup
(classifies_recovery_actions, finalizes_backup_journal_and_lock,
refuses_to_finalize_an_unrelated_backup, refuses_to_finalize_a_backup_without_a_target).round_trips_a_package_rollback_plan,
rejects_a_rollback_plan_for_a_non_package_apply).helper_records_a_launch_failure).rejects_a_missing_or_unknown_journal, rejects_malformed_json,
reports_an_old_format_before_schema_fields, rejects_a_non_sibling_lock_path).App::try_run enters helper mode from RESTART_HELPER_ENV before config/GPUI (compile-time
façade check).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, cargo check -p auro --features updater --locked, and
mdbook build docs pass.| Question | Where it settles |
|---|---|
| Automatic startup recovery and cleanup policy | Apply/restart follow-up |
| Root-owned helper, polkit policy and an OS service/scheduled task | Package elevation |
| Automatic package rollback | Package rollback |
| Journal/backup cleanup policy | Operations follow-up |
| Persistent download resume | Updater resume spec |
| State preservation across the relaunch | Spec 0004 snapshot contract |
Status: Implemented (2026-11-18; .deb/.rpm command execution and helper integration;
pkexec elevation is spec 0029 and caller-supplied rollback,
including the opt-in helper rollback, is
spec 0030; selecting a downgrade target remains out of scope)
Spec 0014 handles a single-file AppImage. This spec covers distribution packages: run dpkg -i for
a staged .deb, or rpm -U for a staged .rpm, through the same shell-free runner used by the
Windows installer.
auro-update::LinuxPackageInstaller: detect .deb/.rpm, run the package manager and classify
its exit code.ApplyKind::DebPackage/ApplyKind::RpmPackage for helper-side apply.sudo, polkit policy installation or an Auro-managed password prompt.dpkg, apt, rpm, dnf or zypper; this uses the low-level package tool.The staged extension selects the command:
| Format | Program | Arguments |
|---|---|---|
.deb | /usr/bin/dpkg | -i <artifact> |
.rpm | /usr/bin/rpm | -U <artifact> |
InstallerRunner receives an argument vector and uses std::process::Command directly. The
absolute paths avoid a PATH hijack; no shell or command string is built. Exit 0 succeeds and any
other code is InstallerFailed.
Rejected: invoking a package manager through a shell. It adds quoting and path-injection risk. Rejected: auto-detecting APT/DNF/Zypper. The low-level tool is deterministic; dependency policy belongs to a later package-manager spec.
LinuxPackageInstaller::new() runs as the current user; a package manager that needs root fails
with InstallerFailed. The restart helper uses the explicit pkexec policy in
spec 0029 for DebPackage/RpmPackage. The app itself never
self-elevates, and sudo is not used.
A prepared journal can carry ApplyKind::DebPackage or ApplyKind::RpmPackage; the helper applies
the staged package through LinuxPackageInstaller before relaunching. No backup is recorded because
the package manager owns the transaction. If the plan also carries a PackageRollback and the apply
fails with InstallerFailed, the helper runs the caller-supplied older package as
spec 0030 describes. Otherwise it records Failed and does not
relaunch.
#![allow(unused)] fn main() { pub enum LinuxPackageKind { Deb, Rpm } pub enum LinuxElevation { None, Pkexec } pub struct LinuxPackageInstaller { /* runner, elevation */ } impl LinuxPackageInstaller { pub fn new() -> Self; // direct pub fn elevated(self) -> Self; // pkexec, spec 0029 pub fn with_runner(runner: impl InstallerRunner + 'static) -> Self; pub fn install( &self, staged: &StagedUpdate, ) -> Result<LinuxPackageKind, UpdateError>; } }
ApplyKind gains DebPackage and RpmPackage. Errors reuse UnsupportedInstaller,
StagedArtifactMissing and InstallerFailed.
Usage:
let kind = auro::update::LinuxPackageKind::from_path(staged.path()).unwrap();
let journal = auro::update::ApplyJournal::create_for_apply(
state_dir.join("apply.json"),
manifest.version.clone(),
auro::update::ApplyPlan::new(
auro::update::ApplyKind::DebPackage,
staged.path().to_path_buf(),
None,
manifest.clone(),
updater.public_key(),
),
auro::update::Relaunch::current()?,
)?;
journal.spawn_helper()?;
cx.quit();
The snippet is an intended call shape, not an app that exists yet.
.deb runs /usr/bin/dpkg -i <staged> (runs_dpkg_for_a_deb)..rpm runs /usr/bin/rpm -U <staged> (runs_rpm_for_an_rpm).InstallerFailed (reports_package_manager_failure).
Elevated failures are ElevationFailed (reports_pkexec_authorization_failure).UnsupportedInstaller (rejects_unknown_artifacts).ApplyKind::DebPackage/RpmPackage dispatch through the elevated helper on Linux.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, cargo test -p auro-services --features tray --locked,
and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Root-owned helper and narrowed polkit policy | Package elevation |
| Automatic package rollback and downgrade policy | Package rollback |
| apt/dnf/zypper policy and dependency repair | Package-manager spec |
| Package signature verification | Release/package trust spec |
| Restart scheduling after package install | Apply/restart follow-up |
Status: Implemented (2026-11-18; bsdiff-compatible deltas and deterministic percentage rollout)
Spec 0012's flat manifest and spec 0013's full-artifact staging are enough to ship, but not enough to save bandwidth or release gradually. This spec adds two optional, signed fields to manifest format v2 and the runtime paths that consume them.
delta and rollout metadata.create_delta: produce a bsdiff-compatible patch.Manifest::with_delta and Manifest::with_rollout.Updater::stage_delta_from_path and download_delta: verify a base, verify the patch, apply it,
then verify and stage the full artifact.Updater::with_rollout_key: deterministic selection for a percentage rollout.auro delta and the matching auro manifest delta/rollout options.download_delta; the caller can fall back to download.FORMAT_VERSION is now 2. A v2 manifest keeps the v1 fields and adds optional:
"delta": {
"from_version": "1.0.0",
"from_sha256": "<base sha256>",
"url": "https://example.test/app-1.0.0.patch",
"size": 1234,
"sha256": "<patch sha256>"
},
"rollout": { "percentage": 25 }
Both are omitted when absent, so a full v2 manifest has the same shape as v1 plus format: 2. The
signature payload includes whichever optional fields are present. Unknown fields remain rejected;
invalid hashes, empty delta URLs/versions and percentages above 100 are typed errors.
Rejected: an unsigned sidecar for rollout/delta. It would let a mirror change who receives an update without invalidating the release signature.
auro delta and create_delta use qbsdiff to produce a bsdiff 4-compatible patch. A delta carries
the base version and SHA-256. stage_delta_from_path/download_delta:
The patch is not trusted just because it came over HTTPS; the signed manifest covers its hash and the resulting full artifact is re-verified.
Rejected: applying a patch in place without a full-artifact hash. A bad patch must not become the installed artifact.
Rollout { percentage } is selected per install. Updater::with_rollout_key supplies a stable
local key; the bucket is SHA-256 of key + version + artifact hash, reduced modulo 100. 0 is
always held back, 100 is always available, and a partial rollout with no key is held back. The
same key/version/artifact always selects the same bucket.
UpdateDecision gains HeldBack; download/download_delta return UpdateError::HeldBack rather
than downloading. A future server can publish a 100% manifest to force completion.
Rejected: random per-launch selection. It flaps users between available and held back. Rejected: using the machine hostname or username directly; the caller supplies a stable, app-owned key.
download is unchanged and does not require a delta. An app that has no suitable base, or receives
DeltaBaseMismatch/DeltaVersionMismatch, can call download for the full artifact. This keeps the
failure mode explicit and preserves the existing staging contract.
#![allow(unused)] fn main() { pub enum UpdateDecision { UpToDate, Available, HeldBack, Downgrade } pub struct Delta { pub from_version: String, pub from_sha256: String, pub url: String, pub size: u64, pub sha256: String, } pub struct Rollout { pub percentage: u8 } impl Manifest { pub fn with_delta(self, delta: Delta) -> Self; pub fn with_rollout(self, rollout: Rollout) -> Self; } pub fn create_delta(base: &Path, target: &Path) -> Result<Vec<u8>, UpdateError>; impl Updater { pub fn with_rollout_key(self, key: impl Into<String>) -> Self; pub fn download_delta( &self, manifest: &Manifest, base: &Path, ) -> Result<StagedUpdate, UpdateError>; pub fn stage_delta_from_path( &self, manifest: &Manifest, base: &Path, patch: &Path, ) -> Result<StagedUpdate, UpdateError>; } }
CLI:
auro delta --from old.bin --to new.bin --out app.patch
auro manifest --artifact new.bin ... \
--rollout-percentage 25 \
--delta-from old.bin --delta-from-version 1.0.0 \
--delta-url https://example.test/app.patch --delta-out app.patch
UpdateError adds HeldBack, DeltaMissing, DeltaBaseMismatch and DeltaVersionMismatch.
FORMAT_VERSION is 2; v1 manifests are rejected with UnsupportedFormat(2).
signs_delta_and_rollout_metadata, rejects_an_invalid_rollout_percentage).applies_a_local_delta_and_verifies_the_full_artifact).rejects_a_delta_for_the_wrong_base).HeldBack, 100% is Available, a partial rollout without a key is held, and a key selects
deterministically (staged_rollout_is_deterministic_and_gates_downloads).creates_a_patch_file,
writes_delta_metadata_and_rollout).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Server-side percentage control without a new manifest | Rollout service follow-up |
| Delta chains and reverse deltas | Delta follow-up |
| Delta telemetry and bandwidth accounting | Release metrics follow-up |
| Channel policy and forced 100% completion | Release UX/spec |
Status: Implemented (2026-11-18; helper-side pkexec package apply, explicit opt-in)
Spec 0027 runs dpkg -i/rpm -U shell-free but leaves the process unprivileged. This spec adds one
elevation path for the restart helper: authenticate through polkit and let the package manager run as
root. The app process never becomes root.
LinuxElevation: None (direct) or Pkexec (polkit).LinuxPackageInstaller::elevated() and with_elevation.pkexec /usr/bin/dpkg -i ... or
pkexec /usr/bin/rpm -U ..../proc/<pid>/fd/<fd>.UpdateError::ElevationFailed for a non-zero pkexec result.sudo, password prompts implemented by Auro, or interactive terminal policy.LinuxPackageInstaller::new() keeps the unprivileged behavior from spec 0027. .elevated() selects
LinuxElevation::Pkexec; the restart helper uses that path for ApplyKind::DebPackage and
ApplyKind::RpmPackage. The app never calls setuid, re-executes itself as root, or wraps the
package manager in a shell.
Rejected: making the whole app root. It gives package-manager and maintainer-script code the
app's environment and UI lifetime. Rejected: automatic sudo. It can block on a terminal that a
GUI app does not have.
pkexec gets an argument vector, not a command stringThe elevated command is:
/usr/bin/pkexec /usr/bin/dpkg -i /proc/<helper-pid>/fd/<fd>
/usr/bin/pkexec /usr/bin/rpm -U /proc/<helper-pid>/fd/<fd>
All program paths are absolute. The package path is a held, read-only descriptor opened by the
helper immediately before the call; the helper keeps the File alive until pkexec returns, so a
path replacement cannot silently redirect the package. The journal verifies the manifest, platform
and artifact before this point.
Rejected: /bin/sh -c "pkexec dpkg -i $path". It adds quoting and injection risk for no gain.
Rejected: sudo. It is not guaranteed to exist, may require a TTY, and has different policy
semantics from the desktop polkit agent.
pkexec exit 0 succeeds. Codes 126 (authorization/execution failed) and 127 (invalid
authorization or missing command), or termination without a code, are ElevationFailed { program, code }. Any other non-zero code is the package manager's own status: pkexec passes the child's
exit code through, so code 1 from dpkg must not be reported as an authorization failure. That
case is InstallerFailed { path, code }, which is also what the journal uses to decide whether an
opt-in package rollback may run (spec 0030). A missing
/usr/bin/pkexec itself surfaces as an I/O error. The helper records Failed in the journal and
does not relaunch the app.
A package manager transaction is not rolled back by Auro. dpkg/rpm own their database and may
leave a package installed even when a later trigger fails; automatic downgrade would be less safe
than the package manager's own recovery. Target is not used for packages.
The command relies on the standard org.freedesktop.policykit.exec action and a running polkit
authentication agent. A distro that wants a narrower, branded prompt should install a policy for a
dedicated root-owned helper; that is deliberately a future change. A headless session without an
agent fails closed with ElevationFailed.
#![allow(unused)] fn main() { pub enum LinuxElevation { None, Pkexec } pub struct LinuxPackageInstaller { /* runner, elevation */ } impl LinuxPackageInstaller { pub fn new() -> Self; // direct, no elevation pub fn elevated(self) -> Self; // polkit through pkexec pub fn with_elevation( runner: impl InstallerRunner + 'static, elevation: LinuxElevation, ) -> Self; pub fn install(&self, staged: &StagedUpdate) -> Result<LinuxPackageKind, UpdateError>; } }
UpdateError adds ElevationFailed { program: PathBuf, code: Option<i32> }.
.deb still runs /usr/bin/dpkg -i <staged> (runs_dpkg_for_a_deb)..deb runs pkexec with /usr/bin/dpkg, -i, and a /proc/<pid>/fd/<fd> path
(elevated_deb_runs_pkexec_dpkg_with_a_held_descriptor)..rpm runs pkexec with /usr/bin/rpm -U (elevated_rpm_runs_pkexec_rpm).pkexec exit of 126 is ElevationFailed (reports_pkexec_authorization_failure).pkexec is InstallerFailed
(elevated_package_manager_failure_is_an_installer_failure).ApplyKind::DebPackage/RpmPackage through the elevated installer.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Root-owned helper and a branded polkit policy | Packaging/distro follow-up |
| Package rollback and downgrade policy | Package rollback |
| apt/dnf/zypper policy and dependency repair | Package-manager spec |
| Headless/SSH authorization | Operations follow-up |
Status: Implemented (2026-11-18; explicit caller-supplied rollback package staged through the updater, plus an opt-in helper rollback when a package-manager apply fails; Auro never obtains a previous package on its own)
Spec 0027 applies a staged .deb/.rpm and spec 0029 elevates that path. A failed or unwanted
package update still needs an exit. This spec adds an explicit rollback operation for an older
package that the caller already has; it does not invent, download or derive one.
Updater::stage_rollback_from_path and Updater::download_rollback for a signed, strictly older
manifest and artifact.LinuxPackageInstaller::rollback(&StagedUpdate).PackageRollback and ApplyPlan::with_package_rollback for an opt-in automatic rollback..deb/.rpm apply fails with InstallerFailed.dpkg --force-downgrade -i for a .deb.rpm -U --oldpackage for an .rpm.LinuxElevation::Pkexec and the held-descriptor command path.InstallerFailed/ElevationFailed on failure.rollback takes the same StagedUpdate contract as install. The caller must authenticate,
download and stage the older package; the manifest/artifact verification that produced it is the
caller's responsibility. Auro does not query the package manager for a cached package or guess a
version.
The staging side has an explicit rollback path, because the normal updater refuses to stage an older version:
#![allow(unused)] fn main() { impl Updater { pub fn stage_rollback_from_path( &self, manifest: &Manifest, artifact: &Path, ) -> Result<StagedUpdate, UpdateError>; pub fn download_rollback(&self, manifest: &Manifest) -> Result<StagedUpdate, UpdateError>; } }
Both verify the manifest signature, format, platform and artifact size/SHA-256 exactly like
spec 0013, then require offered < running. Equal or newer offers are
NotOlder. This keeps a signed older manifest from being replayed through the normal update path
while still allowing a deliberate rollback.
Rejected: selecting a previous version from the package manager cache. The cache is not an update contract, may contain untrusted local state, and differs between dpkg and rpm. Rejected: using the network inside the installer. Download policy and signature verification belong to the updater, not to the privileged apply step.
| Format | Program | Arguments |
|---|---|---|
.deb | /usr/bin/dpkg | --force-downgrade -i <artifact> |
.rpm | /usr/bin/rpm | -U --oldpackage <artifact> |
The flags are explicit so a rollback is not silently interpreted as a normal upgrade. dpkg's
manual warns that it does not perform dependency checking on downgrades; that risk belongs to the
caller and the package manager, not to an implicit Auro policy.
Rejected: dpkg -i without the downgrade flag. It makes the operation depend on the installed
dpkg version's default and obscures intent. Rejected: removing and reinstalling a package; that
loses configuration and is not a rollback.
The rollback path uses the same LinuxElevation::Pkexec held-descriptor command as install.
pkexec codes 126/127 (authorization/execution) are ElevationFailed; a package-manager
failure is InstallerFailed (spec 0029). The operation never
relaunches the app itself.
ApplyPlan::with_package_rollback attaches an already-staged older package to a
DebPackage/RpmPackage plan. The journal stores the older artifact, its signed manifest and its
pinned key. If the primary apply fails with InstallerFailed, the helper:
rollback path (dpkg --force-downgrade/rpm -U --oldpackage);RolledBack and relaunches the old app without overwriting that state.It does not roll back on ElevationFailed (the user declined or pkexec failed), a missing or
tampered artifact, a platform mismatch, or any non-package apply. Those are not evidence that the
package manager changed the installation. A rollback failure leaves the journal Failed with both
the apply and rollback diagnostics.
The caller still chooses the target version and supplies the package. Auro does not keep a
package-manager cache, synthesize a .deb/.rpm from installed files, or decide that a downgrade
is dependency-safe. RollbackVersionNotOlder rejects a same/newer "rollback"
(ADR 0021).
#![allow(unused)] fn main() { impl LinuxPackageInstaller { pub fn rollback(&self, staged: &StagedUpdate) -> Result<LinuxPackageKind, UpdateError>; } pub struct PackageRollback { pub artifact: PathBuf, pub manifest: Manifest, pub public_key: PublicKey, } impl ApplyPlan { pub fn with_package_rollback(self, rollback: PackageRollback) -> Self; } impl ApplyJournal { pub fn rollback_artifact(&self) -> Option<&Path>; } }
The method uses the same LinuxElevation policy as install:
let older_staged = updater.stage_rollback_from_path(&older_manifest, &older_package)?;
let installer = auro::update::LinuxPackageInstaller::new().elevated();
let kind = installer.rollback(&older_staged)?;
The snippet is an intended call shape; obtaining and authorizing older_manifest and
older_package is app/release policy. For an automatic retry after a package-manager failure,
attach the same staged package to the plan:
let plan = ApplyPlan::new(
ApplyKind::DebPackage,
staged.path(),
None,
manifest,
updater.public_key(),
)
.with_package_rollback(PackageRollback::new(
older_staged.path(),
older_manifest,
updater.public_key(),
));
.rpm rollback runs /usr/bin/rpm -U --oldpackage <staged>
(rollback_rpm_uses_oldpackage)..deb rollback runs /usr/bin/dpkg --force-downgrade -i <staged>
(rollback_deb_forces_a_downgrade)./proc/<pid>/fd/<fd> path through pkexec
(elevated_rollback_uses_the_held_descriptor).InstallerFailed with the exit code
(rollback_reports_package_manager_failure).StagedArtifactMissing/UnsupportedInstaller).stage_rollback_from_path stages a signed older artifact, reuses a staged file that still
verifies, and rejects equal/newer offers with NotOlder
(stages_a_signed_older_artifact_for_rollback,
rollback_staging_rejects_newer_equal_and_tampered_offers).download_rollback stages a signed older artifact and refuses a newer one before the network
(downloads_a_signed_rollback_artifact, refuses_a_rollback_download_before_the_network).round_trips_a_package_rollback_plan, rejects_a_rollback_plan_for_a_non_package_apply).rollback_verification_requires_an_older_verified_package), and an elevated
package-manager failure is InstallerFailed so the auto-rollback branch can see it
(elevated_package_manager_failure_is_an_installer_failure).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| Automatic rollback with a package obtained by Auro | Package transaction policy; Auro cannot obtain a previous package |
Automatic rollback of AppImage/MSI/.app applies | Platform installer receipts (specs 0014/0025) |
| Retaining or downloading the previous package | Release artifact retention |
| Dependency-safe downgrade and holds | Package-manager policy |
| Journal-driven rollback execution | Apply journal follow-up |
Status: Implemented in tree (2026-11-18; .pkg command execution, explicit osascript elevation
and helper integration). macOS runtime execution and notarization are not verified on this host.
Spec 0025 applies a .app bundle from a staged .zip. This spec adds the macOS installer-package
path: a staged .pkg is run through /usr/sbin/installer, directly or through the standard macOS
administrator prompt.
MacPkgInstaller: detect .pkg, run /usr/sbin/installer -pkg <staged> -target /.MacPkgElevation::{None, Osascript}.ApplyKind::MacPkg for helper-side apply..dmg mounting and copying.sudo, or a custom Authorization Services prompt.| Mode | Program | Arguments |
|---|---|---|
| Direct | /usr/sbin/installer | -pkg <staged> -target / |
| Elevated | /usr/bin/osascript | fixed run script plus the staged path as its argument |
The direct path uses InstallerRunner and an argument vector. No shell string is built in Auro
code. installer is the supported macOS package tool; open/Installer.app is a UI path, not a
silent apply primitive.
The elevated path runs a fixed AppleScript:
on run argv
do shell script "/usr/sbin/installer -pkg " & quoted form of item 1 of argv & " -target /" with administrator privileges
end run
The package path travels as argv, and quoted form performs shell quoting; Auro never
interpolates an untrusted path into script source. The app process remains the user; only
installer runs as root after the standard macOS authorization prompt.
Rejected: sudo. It assumes a terminal/credential cache and does not provide the desktop
authorization sheet. Rejected: making the app root. Rejected: a custom privileged helper
before its installation and signing story exists.
The path is still reopened by the privileged installer after the journal's verification, so a same-user artifact replacement between verification and apply remains a residual risk until a root-owned helper owns the staged copy. The helper limits that window and records failure.
Direct installer exit 0 succeeds; another code is InstallerFailed. For the elevated path, a
non-zero osascript result is ElevationFailed (AppleScript does not expose the child installer's
exit code through do shell script); the journal records Failed and the helper does not relaunch.
The macOS installer owns its package transaction; Auro does not roll back or repair dependencies.
A missing staged artifact is StagedArtifactMissing; an extension other than .pkg is
UnsupportedInstaller.
#![allow(unused)] fn main() { pub enum MacPkgElevation { None, Osascript } pub struct MacPkgInstaller { /* runner, elevation */ } impl MacPkgInstaller { pub fn new() -> Self; // direct pub fn elevated(self) -> Self; // osascript administrator prompt pub fn with_runner(runner: impl InstallerRunner + 'static) -> Self; pub fn with_elevation( runner: impl InstallerRunner + 'static, elevation: MacPkgElevation, ) -> Self; pub fn install(&self, staged: &StagedUpdate) -> Result<(), UpdateError>; } }
ApplyKind gains MacPkg. The type is re-exported on macOS and compiled under cfg(test) for
command construction tests on other hosts.
Usage:
let installer = auro::update::MacPkgInstaller::new().elevated();
installer.install(&staged)?;
The snippet is an intended call shape, not an app that exists yet.
.pkg runs /usr/sbin/installer -pkg <staged> -target /
(runs_the_macos_installer_for_a_pkg)..pkg runs osascript with the fixed quoted form script and the path as its argument
(elevated_pkg_uses_osascript_and_quoted_form).InstallerFailed (reports_pkg_installer_failure).ElevationFailed
(reports_osascript_authorization_failure).None elevation policy runs the direct installer
(explicit_none_elevation_runs_the_direct_installer)..pkg artifact is UnsupportedInstaller (rejects_unknown_artifacts).ApplyKind::MacPkg dispatches through the elevated installer on macOS.cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| macOS runtime verification and signed-package policy | macOS release CI/spec |
| Notarization and Gatekeeper assessment | macOS notarization |
| Root-owned privileged helper and artifact-copy ownership | macOS hardening follow-up |
| Automatic rollback/uninstall policy | Package transaction policy |
Status: Implemented in tree (2026-11-18; keychain-profile submission, stapling, local
verification, .app bundle archiving and opt-in auro bundle integration). Apple credentials, a
notarized artifact and macOS runtime verification are not available on this host.
Apple distributes signed macOS software through notarization. tauri-bundler handles packaging and
codesigning inputs, but it does not replace the release operator's notarytool submission. This spec
adds the smallest explicit release command: submit an artifact with an existing keychain profile,
then staple the ticket.
auro notarize --artifact <path> --profile <keychain-profile>.auro notarize --artifact <path> --verify for local ticket and Gatekeeper checks.MacNotarizer/NotarizeRunner in auro-bundle.xcrun notarytool submit <artifact> --keychain-profile <profile> --wait.xcrun stapler staple <artifact> unless --skip-staple is set, then
xcrun stapler validate <artifact>..app bundles are zipped with ditto -c -k --keepParent for submission and the ticket is
stapled to the bundle.[bundle.macos] notarize-profile makes auro bundle notarize and verify each produced
.app/.dmg.spctl --assess is a
local check, not a formal notarization result..app..app ticket is stapled.notarytool is invoked shell-free with an absolute xcrunMacNotarizer builds an argument vector and runs /usr/bin/xcrun through NotarizeRunner:
/usr/bin/xcrun notarytool submit <artifact> --keychain-profile <profile> --wait
/usr/bin/xcrun stapler staple <artifact>
No shell, command string, PATH lookup or credential in argv. The profile name identifies an entry
created with xcrun notarytool store-credentials; Auro never reads or prints the password.
Rejected: embedding Apple ID/password/API key in Auro.toml or environment variables. A
keychain profile is the supported macOS secret boundary. Rejected: calling notarytool through
a shell string; it adds quoting risk without a capability.
Submission must succeed before stapling; a failed submission does not start stapling and a failed
staple does not start validation. --skip-staple is for release pipelines that staple a downloaded
copy elsewhere or deliberately defer it. A non-zero command is an AuroError::Bundle with the
action and exit code. The command does not delete, modify or re-sign the artifact.
--verify is the offline half: xcrun stapler validate proves the ticket is attached and
spctl --assess asks Gatekeeper whether the artifact is accepted for its type (.app is
execute, .pkg is install, .dmg is an open primary-signature check). It does not
resubmit and does not prove a real user can launch the app.
A bare .zip is submitted only with --skip-staple; a ticket cannot be stapled to a zip, and
silently skipping that step would misrepresent the result.
The updater already verifies the signed manifest and artifact hash. Notarization adds an Apple Gatekeeper claim; it does not replace the Auro signature, and a missing ticket must not be silently treated as a successful release. Runtime Gatekeeper acceptance is a separate macOS verification.
auro bundle integration is opt-in and post-hocSetting [bundle.macos] notarize-profile makes auro bundle call the same MacNotarizer after
the bundler returns. App bundles are processed before disk images. Because tauri-bundler has
already built the DMG from the app, stapling the app afterwards does not update the copy inside
that DMG; a first launch that must be accepted offline should either use the bundler's
environment-credential path (which notarizes the app before the DMG is built) or rebuild the DMG
after stapling. The integration is a release convenience, not a claim that ordering is solved.
If tauri-bundler already notarized the app from APPLE_* environment credentials, the profile
path submits it a second time. Use one credential path per release. On hosts that cannot produce
macOS artifacts, the key is ignored: a Linux or Windows bundle run still produces its native
formats and does not attempt an Apple command.
#![allow(unused)] fn main() { pub trait NotarizeRunner { fn run(&self, program: &Path, args: &[OsString]) -> Result<Option<i32>, AuroError>; } pub struct SystemNotarizeRunner; pub struct MacNotarizer { /* runner */ } impl MacNotarizer { pub fn new() -> Self; pub fn with_runner(runner: impl NotarizeRunner + 'static) -> Self; pub fn notarize( &self, artifact: &Path, profile: &str, skip_staple: bool, ) -> Result<(), AuroError>; pub fn verify(&self, artifact: &Path) -> Result<(), AuroError>; pub fn notarize_artifacts( &self, artifacts: &[PathBuf], profile: &str, ) -> Result<(), AuroError>; } }
CLI:
auro notarize --artifact target/release/bundle/dmg/Demo.dmg --profile auro-release
auro notarize --artifact Demo.pkg --profile auro-release --skip-staple
auro notarize --artifact target/release/bundle/macos/Demo.app --verify
Config:
[bundle.macos]
notarize-profile = "auro-release"
A missing artifact, a missing .app directory, an empty profile, or an unsupported extension is
rejected before any command runs.
xcrun argument vectors
(submits_staples_and_validates_with_xcrun).--skip-staple/skip_staple=true runs only submission (can_skip_stapling).reports_submission_failure_and_does_not_staple).reports_stapling_failure_and_does_not_validate,
reports_stapler_validation_failure)..app is archived with ditto --keepParent, submitted as a zip, and the ticket is stapled
and validated on the bundle (zips_and_notarizes_an_app_bundle).--skip-staple (a_zip_needs_skip_staple_and_then_submits_only).verify runs stapler validate and the correct spctl --assess arguments for .app, .pkg
and .dmg (verifies_app_pkg_and_dmg_with_stapler_and_gatekeeper) and reports rejection
(reports_gatekeeper_rejection).notarize_artifacts processes .app before .dmg and ignores non-macOS formats
(notarizes_and_verifies_macos_artifacts_and_skips_other_formats).rejects_a_missing_artifact_empty_profile_or_unknown_extension).cargo fmt --all --check,
cargo clippy --workspace --all-targets --locked -- -D warnings,
cargo test --workspace --locked, and mdbook build docs pass.| Question | Where it settles |
|---|---|
| CI keychain profile and Apple credential policy | Release CI follow-up |
Real notarytool submission and Gatekeeper acceptance on a Mac | macOS release verification/credentials |
DMG ordering with a stapled .app | macOS packaging follow-up |
Automatic notarization for a .pkg built outside tauri-bundler | macOS packaging follow-up |
Status: Implemented (2026-11-19; Unix tests pass locally, Windows tests pass on GitHub Actions
windows-latest, including the ancestor checks; metadata freshness, rotation and revocation are
proposed in RFC 0001)
Spec 0026 introduced a durable journal and a restart helper. The helper re-verifies the signed manifest and artifact, but the journal itself names the verification key, staged artifact, platform target and relaunch command. This spec closes that local trust boundary. It does not introduce TUF-style repository metadata; that design needs the RFC first.
ApplyJournal path validation before a journal is read, written or used to spawn/await the
helper.ApplyJournal::load opens the journal read-only, validates the opened file, and reads the same
handle. save validates the parent before creating the temporary file and validates the persisted
journal afterwards. open_lock validates the parent and the opened lock handle before the helper
takes the lock. A path that cannot be proven private is UpdateError::JournalTrust; there is no
"warn and continue" mode and no opt-out in the public API.
Path checks are not lexical. They use symlink_metadata/fstat-style metadata on opened handles,
O_NOFOLLOW on Unix and FILE_FLAG_OPEN_REPARSE_POINT on Windows.
Rejected: a string check for .. or a well-known directory prefix. It cannot distinguish a
private directory from a shared one with the same spelling, and it does not survive a rename.
Rejected: trusting the journal because its contents are signed. The signature key travels in the
same file; internal consistency does not establish who wrote it.
The journal file and its immediate parent must be owned by the effective user. The immediate
parent must not have a group/other write bit. A journal file must be a regular file and must not be
group/other writable. A lock file follows the same rule. The journal and lock files are opened
with O_NOFOLLOW, so a symlink at the final path is refused. Parent directories are opened with
O_DIRECTORY and the resolved directory is validated; a private symlinked parent (for example the
macOS /var symlink or a user-owned link to a private data directory) is accepted only when its
resolved owner/mode pass the same checks.
The walk from the immediate parent to the filesystem root rejects an ancestor that is not owned by
the effective user or root, or that is group/other writable without the sticky bit. A root-owned
sticky ancestor such as /tmp is allowed for an ancestor, because another user cannot remove or
rename an entry owned by this user there; the immediate journal directory still has to be private.
New directory components are created with mode 0700; new files are created with mode 0600.
This is a path-replacement check, not a general filesystem immutability claim. The same-user principal can rename its own files; that is out of scope.
The journal, lock, parent and ancestors are opened with FILE_FLAG_OPEN_REPARSE_POINT (and
FILE_FLAG_BACKUP_SEMANTICS for directories). The handle must not carry
FILE_ATTRIBUTE_REPARSE_POINT; a symlink, junction or other reparse point is refused at every
level.
GetSecurityInfo supplies the owner and DACL. The owner must be the current user, SYSTEM,
Administrators, CREATOR OWNER, CREATOR OWNER RIGHTS or TrustedInstaller (the service owns
protected system directories on some installations). For the journal, lock and immediate parent,
every allowed ACE that carries a write/delete/ACL right (FILE_WRITE_DATA, FILE_APPEND_DATA,
FILE_WRITE_EA, FILE_WRITE_ATTRIBUTES, FILE_ADD_FILE, FILE_ADD_SUBDIRECTORY,
FILE_DELETE_CHILD, DELETE, WRITE_DAC, WRITE_OWNER, GENERIC_WRITE, GENERIC_ALL) must
name one of those principals. A missing DACL, an allowed object ACE or any other ACE type is
refused rather than interpreted. Creator-owner ACEs are allowed because the object's owner is
checked separately and only the owner receives them.
Ancestors use a narrower mask: FILE_DELETE_CHILD, DELETE, WRITE_DAC, WRITE_OWNER and
GENERIC_ALL are refused for any other principal. FILE_ADD_FILE/FILE_ADD_SUBDIRECTORY only
create siblings; they cannot replace the journal directory. An INHERIT_ONLY ACE on an ancestor
applies to its children, not to the ancestor's own object, so the walk skips it there and checks
the child when it descends. The default C:\ ACL demonstrates why this distinction matters: it
grants Authenticated Users:(OI)(CI)(IO)(M), which a naive ancestor check would turn into a
false rejection of every profile path.
The Windows tests in this change ran on GitHub Actions windows-latest and passed: a private
journal directory is accepted, a junction directory is refused, a permissive icacls DACL is
refused, a permissive ancestor DACL is refused, and a symlinked journal is refused (the symlink
test skips when the runner lacks the symlink privilege). This is Windows runtime evidence from CI,
not from the Linux development host.
UpdateError adds:
#![allow(unused)] fn main() { #[error("update journal path `{}` is not trusted: {reason}", .path.display())] JournalTrust { path: PathBuf, reason: &'static str }, }
crates/auro-update/src/trust.rs is private to the crate:
#![allow(unused)] fn main() { pub(crate) fn open_journal(path: &Path) -> Result<File, UpdateError>; pub(crate) fn validate_parent(path: &Path) -> Result<(), UpdateError>; pub(crate) fn open_lock(path: &Path, create: bool) -> Result<File, UpdateError>; pub(crate) fn validate_lock_path(path: &Path) -> Result<(), UpdateError>; }
ApplyJournal::load maps a missing journal to JournalMissing before the path check can turn it
into an I/O error. The lock path must still be the journal's sibling; that rule is checked before
the lock path itself is opened.
Unix tests in crates/auro-update/src/journal.rs:
accepts_a_private_journal_directory_and_filerejects_a_world_writable_journal_directoryrejects_a_world_writable_journal_filerejects_a_symlinked_journalrejects_a_shared_ancestor_directoryrefuses_a_symlinked_lock_fileaccepts_a_journal_in_a_private_symlinked_directoryrefuses_to_create_a_journal_in_a_shared_directoryThe existing journal/helper tests continue to pass (101 tests in auro-update on Linux). The
Windows job runs the same crate tests; the windows-latest CI log shows 78 auro-update tests
passing, including windows_accepts_a_private_journal_directory,
windows_rejects_a_permissive_ancestor_dacl,
windows_rejects_a_junction_journal_directory, windows_rejects_a_permissive_journal_dacl and
windows_rejects_a_symlinked_journal_file. The local Linux host cannot run the Windows code; the
full-crate Windows cross-check is also blocked here by ring's C build requiring lib.exe.
cargo fmt --all --check, cargo clippy -p auro-update --all-targets -- -D warnings,
cargo test -p auro-update, and mdbook build docs must pass.
| Question | Where it settles |
|---|---|
| Windows effective-access model beyond the DACL walk | Follow-up; the current walk is deliberately fail-closed |
| Windows symlink privilege coverage on runners without developer mode | CI follow-up; the test skips rather than failing |
| Staging-directory and installer-handoff TOCTOU | RFC 0001 |
| Metadata expiry, generation, key rotation, revocation and mirror policy | RFC 0001 |
Nothing has been released. This table states what the roadmap promises at 1.0 and what is actually verified today. A row moves to "verified" only when CI exercises it on every pull request.
| Tier | Platform | Minimum | Targets |
|---|---|---|---|
| 1 | macOS | 12 (Monterey) | aarch64-apple-darwin, x86_64-apple-darwin |
| 1 | Linux | Ubuntu 22.04 | X11 and Wayland, x86_64-unknown-linux-gnu |
| 1 | Windows | 10 | x86_64-pc-windows-msvc |
Tier 1 means: builds in CI, tests run, a maintainer uses it, regressions are release blockers.
Measured against CI run 44339911191 (push of af7c224, 2026-11-18): CI, Docs and Bundle smoke
all succeeded. "Not verified" still means no maintainer has exercised a real desktop session.
| Platform | Builds | Tests | Manually used | Notes |
|---|---|---|---|---|
| macOS | CI clippy green | CI tests green | - | Format step runs only on the Linux leg; no desktop-session verification; notarization and .pkg execution unverified |
| Linux (X11) | ubuntu-latest and ubuntu-22.04 CI green | ubuntu-latest fmt, clippy and tests green | - | No desktop-session verification |
| Linux (Wayland) | unverified in CI | unverified in CI | local only (niri) | Phase 0/1 demos, hot-reload measurements and auro bench were run locally on niri/Wayland; no CI compositor job |
| Windows | CI clippy green | CI tests green | - | No desktop-session verification; MSI/NSIS install was exercised manually on Windows 11 earlier in Phase 2, the gate run does not install |
Text input, IME and accessibility have their own audit in Text input, IME and accessibility: GPUI 0.2.2 has IME plumbing on all three platforms but no AccessKit, and Auro has no text-input primitive.
.pkg and notarization paths are command-tested but not run against Apple services;
Windows MSI/NSIS is not installed by the CI gate. Both remain manual verification lines.The CI job installs exactly this set to build the workspace
(.github/workflows/ci.yml):
sudo apt-get install -y --no-install-recommends \
libxkbcommon-dev libxkbcommon-x11-dev libwayland-dev libx11-xcb-dev \
libvulkan-dev libasound2-dev libfontconfig-dev libssl-dev pkg-config
The tray service talks StatusNotifierItem over D-Bus, so it needs no GTK or AppIndicator development libraries.
Contributors on other distributions need the equivalent packages; there is no per-distribution script yet.
The roadmap names immature Windows/Linux support as the biggest schedule risk and commits to publishing the support matrix from Phase 0. Therefore:
These numbers are the product argument. A framework that claims native performance and then ships a 40 MB binary has no reason to exist.
| Metric | Target at 1.0 | Status |
|---|---|---|
| Cold start | < 80 ms | Local 5-run median 154.9 ms (first-frame request, not painted frame) |
| Idle RAM (hello world) | < 40 MB | Local 5-run median 105.3 MB |
| Hello-world binary (stripped) | < 6 MB | Local 15.6 MB |
| Edit to see (boundary data only) | < 500 ms | Met on Linux for the documented warm case; above it on a shared macOS CI runner; not met on Windows. Hot mode (opt-in), four-crate scaffold: Linux 368 ms median save→render for edits in data/src (view_data() -> HotData), N=12, p95 394, 325-394, debug=0 ThinLink, state preserved, patch→render 1-26 ms; the earlier single-crate scaffold measured 521 ms (N=11). Windows (WinBoat, MSVC, interactive session) 813 ms median over nine steady-state patches with the guarded four-crate scaffold (p95 897, 752-897; a plain-boundary four-crate series measured 1168 over nine, and the earlier single-crate scaffold 1375 over five; patch→render 2-16 ms). macOS on a shared macos-26-arm64 CI runner measured 509.5, 837.0 and 956.0 ms medians on three six-warmup runs (N=12 each, p95 1071/2096/1563, 372-2096); a host restart with snapshot restore passed. The runner variance is too large to claim the target there. Relaunch mode still measures 2730 ms save→repaint-requested; an earlier relink-dominated run measured ~60 s. See spec 0004 and hot reload |
| Frame time | 16.6 ms at 60 fps | Inherited from GPUI, unverified |
Precision matters more than the number, because a budget you cannot reproduce is a slogan.
target/debug.strip = "symbols", panic = "abort", .app/MSI/AppImage
payload, not the directory total.auro bench --dir <app> builds the release binary (honoring CARGO_TARGET_DIR the way cargo
does), spawns it --runs times with
AURO_STARTUP_TRACE=1, measures spawn-to-auro:startup (first-frame request), samples RSS after
--idle-seconds, and reports the release binary size. Every sample is retained: the text report
prints min, median, p95 and max for startup and RSS, and --json emits the same summary plus the
raw startup_ms_samples/rss_mb_samples arrays. The p95 uses the nearest-rank definition, so a
small run count (five is the default) makes p95 the maximum sample; raise --runs before reading
it as a tail estimate. A process that exits after the startup marker but before or during the idle
sample is reported as an error with its exit status, never as a 0 MB sample. The marker is a
first-frame request, not proof of a painted frame; the stricter painted-frame method remains a
target. Run it on an otherwise idle machine and record the platform/toolchain with the result.
Local measurement, 2026-11-18, Linux x86_64, niri/Wayland, release build, examples/hello, five
runs with a five-second idle sample: startup median 154.9 ms, idle RSS median 105.3 MB,
stripped binary 15.6 MB. These are alpha measurements, not a published baseline or a Tauri/
Electron comparison; the 1.0 targets above are not met yet.
The roadmap commits to measuring these in CI and failing the build on regression. That is not implemented yet: the harness exists, but there is no committed baseline, pinned runner class or regression gate. When it lands:
perf-regression
label override that requires maintainer approval.Micro-benchmarks use criterion; process-level measurements are separate harnesses, because they
measure a binary rather than a function.
The same-app comparison runs through tools/comparison/bench.py:
one 480x320 window with a single line of text, built in release mode for Auro, Tauri and Electron
on the same machine, measured with the same spawn-to-content-ready, process-tree-RSS/PSS and
uncompressed-payload method. The marker is the nearest available "first content ready" signal
(first frame request for Auro, page parsed for Tauri, ready-to-show for Electron), not a
guaranteed painted frame. Electron's payload includes Chromium; Auro and Tauri use the system
webview/GPU stack. Installer compression is excluded for all three.
Measured 2026-11-19, Linux 7.3.4 x86_64, niri/Wayland, rustc 1.99.1, five runs after one warm-up, 5 s idle. The desktop was not fully idle (Windows VM and browser running; load average 3.5 at start), so treat the absolute numbers as a provisional baseline, not an idle-machine record:
| Target | Startup median | p95 | Idle RSS | Idle PSS | Payload |
|---|---|---|---|---|---|
| Auro (GPUI) | 189.5 ms | 205.3 ms | 105.9 MB | 98.6 MB | 14.9 MB |
| Tauri 2.12.7 (WebKitGTK 2.54.2) | 417.4 ms | 507.6 ms | 500.7 MB | 314.5 MB | 6.7 MB |
| Electron 45.4.1 | 420.5 ms | 451.9 ms | 589.2 MB | 291.1 MB | 273.7 MB |
Raw samples: tools/comparison/baseline.json.
The Tauri result reflects this host's WebKitGTK build; do not generalize it to other webview
versions. RSS sums shared pages per process and overstates multi-process runtimes; PSS is the
comparison number. Auro's payload is larger than Tauri's and above the 6 MB 1.0 target; its startup
and idle memory are the measured advantage here.
This is a disposable spike report, not a migration. It answers one question: what breaks if Auro
moves from gpui = "=0.2.2" to the gpui-pre 0.3.x line, and is the hot-reload path still viable?
WAYLAND_DISPLAY=wayland-1, DISPLAY=:0).gpui-pre =0.3.12 (aliased as gpui), gpui-pre-linux =0.3.12,
gpui-component =0.10.0, accesskit 0.24.1.gpui-pre 0.3.13 exists, but gpui-component 0.10.0 pins gpui-pre =0.3.12. The spike pins the
whole line to 0.3.12; mixing 0.3.12 and 0.3.13 would create two gpui type universes.xattr 0.2.3 vendor patch is unused by this dependency graph; xattr 1.7.0 is in the tree.| Target | Command | Result |
|---|---|---|
auro-ui | cargo check -p auro-ui | pass after 34.8 s of dependency build |
| workspace | cargo check --workspace | pass after 2 API edits |
examples/hello | cargo check | pass |
examples/log-viewer | cargo check with gpui-component =0.10.0 | pass without source changes |
| generated app | auro new + cargo check --features hot-reload | pass after replacing gpui::Timer |
| hot reload | auro dev, [dev] hot = true | pass; 20 boundary edits, same pid |
The first app build through dx took 72.41 s (shared dependency target, cold app crate). A host
rebuild after a types/ui edit took 3.09 s.
A runtime smoke of examples/hello on the same target built in 3m05s (debug) and ran: it printed
auro:startup and was killed by a 10 s timeout while the event loop was still running (expected
for a window app).
Only two workspace call sites needed changes; the generated template needed one more.
Application::new() is gone. gpui-pre now takes a platform: Application::with_platform(Rc<dyn Platform>) or Application::new_inaccessible(...). The platform implementation lives in a
separate crate (gpui-pre-linux, gpui-pre-macos, gpui-pre-windows), and the app chooses it
with current_platform(false)/linux_platform(...). This is an architectural change for Auro:
auro-ui or auro must own the target-specific platform dependency, and auro new/CI must
exercise each platform crate. The spike hardcodes the Linux platform.cx.on_window_closed now takes (cx, WindowId) instead of cx. Auro ignores the id and
recomputes the open-window set, so the change is mechanical.gpui::Timer is no longer re-exported (0.2.2 re-exported smol::Timer). The scaffold used it in
the snapshot debounce; the spike adds smol = "2" to the ui crate and imports smol::Timer.
This is a template change, not a framework API change.Window::focus_next now takes &mut App. crates/auro-ui/tests/button_keyboard.rs:31 calls
window.focus_next() and fails to compile; the test must pass the app context. This is a test
API change that a real migration must include, not just a library call site.gpui_linux::current_platform(false). The CI matrix fails on macOS and
Windows with cannot find module or crate gpui_linux; ubuntu-latest also failed in the first
CI run. A real migration needs target-specific platform crates and a per-target CI leg.gpui-component 0.10.0 compiled the existing log-viewer source without changes. That is a
compile result, not a runtime or visual verification. The spike branch's Linux 22.04 build passes;
the other matrix legs fail for the platform/test reasons above, which is expected for a Linux-only
spike and is recorded rather than hidden.
The existing auro::hot data boundary (view_data() -> HotData, subsecond/dx 0.7.10) works with
gpui-pre 0.3.12. A first edit measured 314 ms save-to-render (patch 272 ms, patch-to-render
0 ms). The app then received a host-only edit (ui/types) and was restarted by auro dev
(host rebuild failed; previous UI still running while the files were inconsistent; then a
successful restart).
For a real layout/tree test, the host was taught to interpret four boundary values (padding,
gap, radius, tree) and to add/remove children from tree. This host change is a restart. The
running host (pid 2413989) then received 20 boundary edits that changed the title, accent, padding,
gap, radius and tree (0/1/2 extra children):
| N | median | min | max | patch-to-render |
|---|---|---|---|---|
| 20 | 296 ms | 285 ms | 415 ms | 0-1 ms |
All 20 edits stayed in the same pid, the host renders counter advanced 5→24, and no relaunch
occurred. The ViewData schema was bumped to 2 and the old host rejected the incompatible frame
during the transition, which is the intended guard.
This is not element-code hot reload. The boundary carries layout values; ui/Render code
still lives in the host and a change there restarts the process. It does show that a data-driven
layout/tree can change in the same process well under the 1 s experimental target.
gpui-pre-macos and gpui-pre-windows exist, but the
spike has no Apple or Windows host and did not cross-compile the full GUI stack.gpui-pre has an optional hot-reload feature that depends on subsecond 0.7.10 and
dioxus-devtools-types; it was not enabled or tested. It may be a better migration path than
Auro's own auro::hot boundary, but that needs its own spike.accesskit 0.24.1, accesskit_unix 0.22.1). A dependency does not
prove functional accessibility: no screen reader, AT-SPI tree inspection, keyboard traversal or
IME test was run. Application::new_inaccessible exists, but the default path was not audited.gpui-component 0.10.0 depends on gpui-pre =0.3.12; a future 0.3.13 pin needs a matching
gpui-component release or a patch.Do not migrate main yet. The migration is smaller than the 0.2.2 feasibility spike suggested
(two workspace call sites, one template dependency), but the platform split, the AccessKit/IME
audit, the Windows runtime and the hot-reload mechanism choice are still open. If Auro decides to
migrate:
gpui-pre =0.3.12, gpui-pre-{linux,macos,windows} =0.3.12, and
gpui-component =0.10.0 together; do not mix 0.3.12 and 0.3.13.auro-ui (the only crate that names GPUI) and add a per-target CI
check for the platform crates.Application::new to the platform factory, on_window_closed to the two-argument
callback, and the focus_next test call site to pass the app context in the same PR.gpui::Timer in the template with smol::Timer (or a deliberate auro-ui re-export)
and add smol to the generated ui crate.examples/hello/log-viewer runtime, then
decide whether to keep auro::hot or evaluate gpui-pre's own hot-reload feature.xattr patch only after the dependency graph proves it is unnecessary./run/media/pdl/data/Projetos/auro-wt-gpui03 (branch agent/gpui-0.3-spike).gpui03-check.log, gpui03-workspace.log in that worktree./tmp/auro-gpui03-dev.log; generated app: /tmp/auro-gpui03-demo.This page is the contract a change to this repository is measured against. It exists so a contributor, a reviewer, or an AI assistant does not have to infer the project's conventions from the last commit.
| Path | Enforces |
|---|---|
README.md | English entry point: what it is, status, how to get involved |
README.pt-BR.md | Portuguese mirror of README.md |
ROADMAP.md | the only place phases, dates and targets are defined |
CONTRIBUTING.md | how to build, test and submit |
SECURITY.md | how to report a vulnerability privately |
CODE_OF_CONDUCT.md | Contributor Covenant 2.1 |
CHANGELOG.md | user-visible changes, Keep a Changelog + SemVer |
LICENSE-MIT, LICENSE-APACHE | dual licence, see ADR 0006 |
.editorconfig | LF endings, UTF-8, 2-space YAML/TOML, 4-space Rust |
AGENTS.md | instructions for AI coding assistants |
rfcs/ | proposals that need discussion before a decision |
docs/ | the published book (mdBook) |
.github/workflows/ci.yml | format, lint, test, docs build |
.github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.md | the shape of a report or a change |
Absent on purpose: CODEOWNERS (one maintainer, the default reviewer is already correct),
release.yml (nothing to release), funding, stale bots and labelers.
README.pt-BR.md is a translation, not a fork. It must contain the same sections, tables and
code samples as the English README. A change to one that is not mirrored in the other is an
incomplete change.type(scope): imperative subject, type one of feat, fix, docs,
refactor, perf, test, build, ci, chore, revert. Subject at most 72 characters, no
trailing period, body explains why.git commit -s), DCO 1.1. There is no CLA.CHANGELOG.md is written by hand at pull-request time under ## [Unreleased], in Keep a
Changelog sections (Added, Changed, Deprecated, Removed, Fixed, Security). No
generated changelog until releases exist.docs/ and is deployed to GitHub Pages.docs/book.toml sets create-missing = false: every entry in docs/src/SUMMARY.md must exist,
and a chapter removed from disk but left in the summary fails the build.SUMMARY.md, and written in the same voice as the rest:
direct, present tense, no marketing adjectives, no emoji.rust,ignore and carry a one-line note saying
the API does not exist.docs/src/decisions/ and is immutable. A
proposal that needs discussion goes to rfcs/ and is numbered. An accepted RFC produces an ADR.cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings and
cargo test --workspace --locked are the gates, and CI runs them on Linux, macOS and Windows.
Cargo.lock is committed. This workspace produces binaries, so the lockfile is part of the
build; --locked makes a dependency change without a lockfile update fail in CI instead of
silently resolving differently.
Dependency licences should be checked, not assumed. Once cargo-deny is configured, a
deny.toml should allow the set compatible with MIT OR Apache-2.0 and flag incompatible
licences on transitive bumps. Until that configuration lands, licence review remains a manual part
of dependency changes.
Every .rs file starts with the SPDX identifier:
#![allow(unused)] fn main() { // SPDX-License-Identifier: MIT OR Apache-2.0 }
The workspace inherits license = "MIT OR Apache-2.0"; a crate that deviates is a review
blocker.
unsafe requires a // SAFETY: comment stating the invariant that makes it sound.
Errors are typed. Library code returns Result<T, AuroError>; unwrap/expect are for tests
and for states the type system proves unreachable, and the latter needs a comment.
No println! for diagnostics in library code; use tracing.
Public items carry a doc comment. A public item without one fails missing_docs once that lint
is enabled at 1.0.
Gates and supporting jobs, all required to be green before merge:
cargo fmt --all --check (Linux leg)cargo clippy --workspace --all-targets --locked -- -D warnings (Linux, macOS, Windows)cargo test --workspace --locked (Linux, macOS, Windows)cargo build --workspace --locked on ubuntu-22.04 (published Linux floor)mdbook build docsactionlint)A red gate is never merged and never "fixed" by disabling the check.
Every third-party action is pinned to a full commit SHA with the version in a comment
(uses: actions/checkout@11d5960... # v4). Dependabot proposes the bumps, so the pin is updated
deliberately rather than following a moving tag under us. Workflows declare least-privilege
permissions, a concurrency group, and a timeout-minutes per job that can hang.