Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

Auro 0.1.0-alpha.7 · native desktop

Desktop apps with a Rust frontend.

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.

The shape of the work

One workspace from install to window.

  1. Scaffold a real app

    auro new writes a four-crate workspace: the bin, the view, the hot boundary and the shared data types.

  2. Run the native loop

    auro dev builds, launches and watches. The default loop rebuilds and restarts; the hot path is opt-in and has a narrower contract.

  3. Build and bundle

    auro build makes a release binary. auro bundle uses the platform packaging paths; support is documented, not assumed.

The boundary

A command is a Rust function.

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?;
What you get

The app model, without the browser.

typed IPC

No stringly bridge

Commands, events and arguments are Rust types. The schema is generated from the same signature the compiler checks.

renderer

GPUI, not a webview

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.

capabilities

Fence the real boundary

Grants are deny-by-default and scoped to filesystem, network, shell, clipboard, notifications and keychain. Most UI code needs no runtime check.

application layer

Keep the boring parts

Config, window management, lifecycle, single-instance, tray, shortcuts and deep links stay in the framework, where Tauri already proved the shape.

release

Signed updates, opt-in

Update manifests are signed, artifacts are hashed and staged, and apply paths are platform-specific. The updater is a feature, not a default.

the loop

Hot reload, measured honestly

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.

Scope

What Auro is not.

  • Not a webview wrapper. The webview is a scoped Phase 4 escape hatch for OAuth and embedded docs, not the foundation.
  • Not a GUI toolkit. GPUI owns the widgets and the renderer. Auro is the application layer around it.
  • Not a GPUI fork. Upstream is pinned, with one thin compatibility module and no GPUI outside auro-ui.
  • Not "CSS for Rust". The UI is a builder API plus design tokens. There is no styling language in 1.0.
Choose a path

Build, inspect, or challenge it.

Alpha means alpha.

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.
  • Hot reload is measured on Linux for the data boundary; Windows and macOS are above the target.
  • Platform rows are published as verified or unverified, not as promises.

Start here

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.

Before you start

You need:

  • Rust stable with cargo on PATH. The scaffold uses edition 2024 and declares rust-version = "1.90".
  • The platform build dependencies. Linux needs the native libraries listed in platform support; macOS and Windows need their normal native build toolchain.
  • The alpha CLI. There is no stable release. The published version is 0.1.0-alpha.7.

The CLI is a cargo-installed binary named auro; the crate is auro-cli.

1. Install the 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.

2. Create the app

auro new hello
cd hello

auro new refuses a non-empty directory. It writes a four-crate workspace plus configuration:

PathRole
Auro.tomlApp identifier, windows, dev watch list, hot-mode switch and bundle icon.
src/main.rsThin 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.

3. Run it

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.

4. Know what the hot path covers

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:

  • A save in data/src is a boundary edit. The patch replaces that function; the running host keeps its window and state.
  • A save in 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.
  • On Linux, boundary-only edits in the generated app measured 368 ms median save-to-render (N=12, 325-394 ms). Windows measured 813 ms median; the shared macOS runner measured 509.5-956 ms across runs. Those are above the 500 ms target.
  • The measurement is for the documented data boundary only. It is not a general layout or view reload, and it is not GA.

The full contract, including failure behavior and what is not reloadable, is in hot reload and spec 0004.

5. Build and bundle

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 .

Where to go next

If you want toRead
Understand the app loopArchitecture overview
Follow a command across threadsThreading and IPC
Change configurationConfiguration
Know what is actually verifiedPlatform support
Know why a decision was madeDecision records
Check the alpha gatesAlpha 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.

Architecture overview

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.

Responsibilities

LayerOwnsMust not
auro-cliproject scaffolding, dev loop, bundling entry points, diagnosticscontain runtime logic the app needs
auro-coreApp, window manager, config, lifecycle, command registry, state store, event bus, single-instance guard and forwardingrender anything
auro-uiGPUI re-export, toolkit seam, tokens, minimal primitivesship a component toolkit; check permissions
auro-ipctyped command transport, schema derivation, event deliverydecide policy
auro-permscapability manifests, runtime enforcement for plugin and content boundariesguard code that the compiler already guards
auro-pluginsplugin manifests, in-process cdylib hosts, out-of-process RPCassume plugin code is trusted
auro-servicesplatform 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-signpackaging per platform, signed manifests, staged downloads, platform apply/rollback and notarization tooling, key handlingrun inside the app's main loop

Data flow of one interaction

  1. Main thread. GPUI owns it. A user event arrives and a view handler runs.
  2. Dispatch. The handler either mutates state directly (cheap, synchronous) or asks the command registry for an async command.
  3. Off-thread work. The command is a plain async fn on the tokio runtime. File I/O, network, parsing - anything that can block - happens here.
  4. Return. The command returns a typed Result<T, AuroError>. There is no serialization boundary unless the command crosses the plugin boundary.
  5. Back to the main thread. The result is applied by updating an 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.

Where state lives

  • UI state lives in GPUI entities on the main thread.
  • Application state lives in the core state store, reachable from commands.
  • Reloadable state is captured as a host-owned 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.

What is not decided yet

Tracked in ROADMAP §8:

  • a scripting layer for plugin UIs, or Rust only;
  • out-of-process plugins first, or in-process first.

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.

Crates and layering

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.

Crates

Eleven crates are materialized now; the rest arrive with the phase that needs them.

CrateKindResponsibilityStatus
aurolibraryfacade re-exporting the supported API surface; services and tray are opt-in featuresPhase 0-2, in tree
auro-clibinarynew, dev, build, bundle, generate-key, manifest, delta, notarize, bench, doctorPhase 0-2, in tree
auro-corelibraryconfig schema, state store, lifecycle events, single-instance guard and forwarding; window manager and event delivery live in the facadePhase 1, in tree (config, state, lifecycle, instance)
auro-uilibraryGPUI re-export, tokens, minimal primitives (Button with keyboard activation); no component toolkit (ADR 0009)Phase 0-2, in tree (re-exports, Button, tokens)
auro-ipclibrarytyped transport, command schemas, runtime bridgePhase 1, in tree
auro-macrosproc-macro#[command], generate_handler!Phase 0, in tree
auro-permslibrarycapability manifests and runtime enforcement (spec 0016)Phase 2, in tree
auro-pluginslibraryplugin manifest and host (in-process and out-of-process)planned, Phase 3
auro-serviceslibraryplatform services: autostart, notifications, keychain, global shortcuts, tray, deep links (specs 0017-0022)Phase 2, in tree
auro-bundlelibraryplatform packaging via tauri-bundler (spec 0010)Phase 2, in tree
auro-signlibraryEd25519 keys, signatures, SHA-256 (spec 0011)Phase 2, in tree
auro-updatelibrarysigned manifests, stage/delta/rollout runtime, platform apply and journal-driven restart/rollback (specs 0012-0014, 0025-0032)Phase 2, in tree

Dependency rules

  1. One direction. A crate may depend on the layer below it. Cycles are a design error, not a Cargo.toml problem.
  2. auro-core composes; it is not a dumping ground. Anything that only one platform or one subcommand needs belongs in that crate.
  3. auro-ui has no policy. No permission checks, no filesystem access, no config reads. A primitive that needs data takes it as an argument.
  4. 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.
  5. GPUI is not re-exported wholesale. auro-ui re-exports only the GPUI surface Auro's primitives use, so upstream churn is absorbed in one place.
  6. No toolkit in the framework. gpui-component and similar crates are application dependencies, initialized through App::setup and wrapped with App::root_with (ADR 0009).

Rules for tracking GPUI upstream

  • Pin GPUI by exact version. Floating a git dependency is how the compat layer becomes a fork.
  • Vendor a patch only when the upstream bug blocks a release; keep the patch in one module with a link to the upstream issue.
  • Nothing outside auro-ui imports gpui directly. That includes examples unless they are explicitly demonstrating the escape hatch.

Naming

  • Crates: auro-* in the manifest, auro_* in code, auro as the user-facing facade.
  • Public API is added to auro::prelude only when it is stable enough to promise.
  • Internal modules may be reorganised freely before 1.0; public items may not move without a changelog entry.

Open questions

  • Whether auro is a separate facade crate or auro-core re-exported under a shorter name.
  • Whether 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.

Threading and IPC

Two rules generate every other rule in this chapter:

  1. GPUI owns the main thread, and all UI mutation happens on it.
  2. Commands run off it and return typed results.

Threading model

WorkThreadMechanism
Rendering, layout, input, focusmainApplication::run
Entity mutationmaincx.update, cx.listener, AsyncApp::update
Spawning async workmain -> runtimecx.spawn
File, network, process, parsingtokio worker threadsasync fn in a command
Plugin RPCworker threadsout-of-process transport

Rules:

  • Never block the main thread. No std::fs, no reqwest::blocking, no Command::output, no synchronous sleep in a render or event handler.
  • Never touch an entity from a worker thread. Move the result to the main thread first, then mutate and cx.notify().
  • Never await while holding a UI borrow. Clone what you need, drop the borrow, then spawn.

What a command is

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:

  • arguments and results implement serde::Serialize / Deserialize plus schemars::JsonSchema, because the plugin boundary still needs a schema;
  • errors are a single AuroError type, with From conversions for std::io::Error and serde_json::Error so ? works in command bodies;
  • commands are registered at app build time, not discovered at runtime by string name.

Why "typed" is the whole point

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

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.
  • A foreground pump drains the queue on the main thread and calls App::on_event::<E> handlers with &E and &mut App.
  • On the main thread, emit(event, cx) dispatches synchronously.
  • Lifecycle events (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.

Error handling

  • Library code returns 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.
  • A command error surfaces to the caller as a value. It does not panic, and it does not get stringified into a dialog by the framework - the app decides how to present it.
  • Panics in plugin code must not take down the host; the plugin boundary catches them and reports a typed failure.

Capabilities

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:

BoundaryWhy it is untrustedEnforced at
Pluginsthird-party code, may be installed after the app shipsplugin host, per call
Contentdocuments opened, scripts evaluated, remote datathe API that consumes it
Webview escape hatcha browser pointed at content we do not controlthe hatch itself, phase 4

Model

  • Deny by default. A plugin manifest lists the scopes it needs: fs, net, shell, clipboard, notification, keychain. Anything unlisted is refused at the call site.
  • Scopes are data, not strings in code. The app ships a manifest; the host compiles it and answers verdicts. A path or host pattern is matched against the compiled form, not re-parsed per call.
  • The check sits next to the effect. 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.
  • Compile-time first. If the compiler can prevent it, a runtime check is not the answer. Do not add a capability for something first-party code does directly.
  • In-process plugins are a feature flag. A 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.

What a denial looks like

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.

Not in scope

  • Sandboxing first-party app code. If the app author writes it, it runs.
  • OS-level sandboxing (App Sandbox, seccomp, AppContainer). Bundle-level sandboxing is a separate discussion, tracked against Phase 2 packaging work.
  • Protecting secrets from the user who owns the machine. Keychain access is about correctness and consent, not about defending against the local user.

Open questions

  • Manifest format: Auro.toml section, or a separate capabilities.json next to the plugin.
  • Whether capability grants are app-wide or per-window for the webview escape hatch.
  • How a plugin upgrade that widens scopes is presented to the user at runtime.

Updates

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.

Trust model

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.

Staging

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.

Apply

ArtifactPathBackup/rollback
AppImageAtomic replacement, mode 0755Hard-link/copy backup, explicit receipt
.debdpkg -i through pkexecPackage manager transaction; opt-in older-package rollback
.rpmrpm -U through pkexecPackage manager transaction; opt-in older-package rollback
MSI/NSISSilent installer, 3010 means rebootInstaller policy
macOS .app zipExtract, swap one bundleRetained bundle backup, explicit receipt
macOS .pkg/usr/sbin/installer, AppleScript authorizationInstaller 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.

Journal and restart

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.

Rollback

  • AppImage and macOS .app installers return a receipt; the old artifact stays beside the target until the app discards it.
  • A Linux package rollback needs an older .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).
  • Auro does not discover, retain or synthesize the older package, and does not decide whether a downgrade is dependency-safe. The package manager owns that transaction.

Notarization and signing

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.

Not implemented

  • a served update channel, metadata expiry/generation, release key rotation and revocation (RFC 0001);
  • a real notarization submission or a macOS .pkg apply on a macOS host;
  • automatic retention of a previous package;
  • an update UI, scheduling, channels or resume of an interrupted download;
  • a public comparison or pinned CI baseline for update size/time.

Choosing a toolkit

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.

The seam

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.

Versions are part of the choice

gpui-component tracks GPUI; Auro pins GPUI exactly. The compatibility line matters:

ToolkitGPUI lineNotes
gpui-component 0.5.1gpui ^0.2.2Last 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.xRequires moving Auro's GPUI pin and revalidating hot reload. Current 0.10.0 pins gpui-pre =0.3.12.
nonegpui 0.2.2div(), 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.

What Auro will not do

  • Add a toolkit to auro-ui or auro-core.
  • Promise that any toolkit version works forever.
  • Present its minimal Button as a component kit.
  • Hide a toolkit's per-window limitations (for example, one global theme).

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.

Hot reload

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.

Contract

  • Default today: 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.
  • Hot reload goal: a warm, view-only change becomes visible in under 500 ms with opted-in state preserved, without closing the window.
  • Honesty rule: a process restart is never presented as hot reload. A failed build keeps the previous UI active. A reload or patch that cannot be applied safely falls back to a state-preserving restart only when state can be restored, and the outcome is labelled explicitly.

Slice 0 finding (2026-11-16)

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).
  • A realistic GPUI-view 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.

Option 1 consolidation (2026-11-16, prototype evidence)

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:

  • Mechanism exercised: explicit stable 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.
  • Minimal-case results: plain Rust 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.
  • Constraints observed: patchable code is tip-crate code reached via hot boundaries (changes outside boundary or init-captured async work not retroactive, e.g. 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.
  • Status: evidenced experimental candidate for the in-process direction on Linux x86_64/GPUI 0.2.2 in minimal conditions; not a D6 claim for representative Auro scaffolds/apps, not integrated into auro dev, and not proven across platforms/profiles.
  • Windows plain prototype follow-up (2026-11-16, WinBoat guest, not integrated): the same non-GPUI tip-crate 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.
  • Windows advanced front/back follow-up (2026-11-16, WinBoat guest, plain non-GPUI, not integrated): a second tip crate rendered through 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.
  • Windows GPUI 0.2.2 follow-up (2026-11-16, WinBoat guest, not integrated): the GPUI prototype built in 181 s (23.9 MB exe) and rendered when launched into the active interactive console session via a scheduled task (/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.

Integrated hot mode (2026-11-18)

[dev] hot = true now runs a usable loop rather than a patch that needed a click to appear:

  • Repaint on commit. The devserver applies a patch without touching GPUI's frame; the app kept the previous frame, and the patched boundary only ran on the next interaction. On Linux this made a patch look applied (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.
  • Measured render. 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).
  • Change classification. A save under 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.
  • Boundary is the reloadable unit. 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.
  • Dev profile. Scaffolded 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.
  • Crate boundary. The scaffold is a four-crate workspace: 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.
  • Apply containment. 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.

Platform status (2026-11-18)

  • Linux: measured above; four-crate scaffold median 368 ms (N=12), integrated loop, state continuity, build-failure recovery, apply containment, schema rejection, graceful exit and Ctrl-C cleanup verified (niri/Wayland).
  • Windows: integrated loop verified in the WinBoat guest (interactive console session 1, MSVC 1.99.0): first patch after launch 2806 ms save-to-render, five steady-state patches 1823/1505/1375/1237/1282 ms (median 1375), patch-to-render 8-38 ms; same pid and ticking host state across patches, a type error kept the previous UI live, the fix reloaded in 1696 ms, and closing the window exited the dev loop with code 0. A four-crate re-test (simple boundary) measured 873/1872/1735/1229/1168/961/820/2359/921 ms (N=9, median 1168, patch-to-render 3-13 ms) with the same pid/window/state: better, still above 500 ms. The guarded 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.
  • macOS: no local Apple host, but a manual workflow (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.

PlatformHot modeSave-to-render (warm)Evidence
Linux x86_64, niri/WaylandOpt-in, verified368 ms median, N=12 (p95 394, 325-394)Four-crate scaffold, desktop-dev, boundary edits, same pid/window/state
Windows 11 x86_64, MSVCOpt-in, verified in interactive session813 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 CI509.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.

Mechanism and layout

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.

State preservation

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.

Fallback

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.

Constraints this imposes on application code

  • Reloadable UI logic must cross explicit, stable hot boundaries; code outside those boundaries (or already captured in running futures/callbacks/init state) must not be assumed to update in place.
  • Views and reloadable state must be reconstructible from host-owned snapshots/state.
  • Reloadable tasks, subscriptions, and callbacks must be cancellable or invalidatable before replaced code can run.
  • Preserved state must live on the host-stable side or in snapshotable form; tip-crate/patch-unit statics, thread-locals, and layout-incompatible values need reset or migration handling.
  • Entity/view handles and callbacks must not be stored in global/static locations that outlive the reload unit or prevent safe invalidation.
  • On Windows/MSVC (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.
  • Only calls that go through 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.
  • Hot patching requires a build with 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.
  • The boundary's return type must keep a fixed layout: the running host was compiled against the old one. The scaffold uses types::HotData, a fixed #[repr(C)] frame with a schema number; change ViewData and its encoder, bump SCHEMA, and never re-lay-out HotData.
  • The patch loader keeps each applied library mapped for the life of the process (unloading live patched code is unsafe). A ~12 KB patch keeps a long session bounded; an app-sized patch would grow the process by hundreds of MB per apply.
  • A patch that cannot be loaded must not kill the listener. auro::hot handles apply_patch errors and loader panics and keeps the previous jump table; the next edit can still apply.
  • A patched boundary must be pure data so a panic can be contained. The generated view wraps 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.

Open problems

  • Hot mode is integrated behind [dev] hot = true; open: change classification for edits outside the boundary (currently a patched, unchanged boundary), forced fallback restart, and a headless reload fixture.
  • Project/layout/build strategy: the four-crate 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.
  • Snapshot format/versioning, incompatible-change classification, and state migration/reset policy.
  • Representative D6 measurements on Auro apps/scaffolds (cold/warm, debug/release, more hardware and Windows/macOS coverage); Linux, Windows and macOS each have one scaffold series.
  • Debugging, symbols, breakpoints, and backtraces through the chosen reload mechanism.
  • Full view-code hot reload on Windows (element-returning hot boundaries crash after apply; the implemented layout keeps elements host-stable), macOS feasibility, signing/entitlements (a hardened-runtime dylib would be refused), debugger behavior, and CI verification beyond compiling the feature.

Text input, IME and accessibility

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.

What Auro exposes

auro-ui currently ships one primitive, Button, and no text-input primitive. The button:

  • is focusable and a tab stop;
  • activates on an unmodified Enter or Space when focused;
  • exposes no accessibility role, label or action beyond its visible child.

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.

What GPUI 0.2.2 provides

A source audit of gpui 0.2.2 (the pinned version) found:

AreaPresent in GPUI 0.2.2Notes
Accessibility/AccessKitNoNo accesskit or accessibility symbol in the crate source or features
Text input handler APIYesplatform::InputHandler, Window::set_input_handler/take_input_handler, ElementInputHandler
IME candidate positioningYesInputHandler::bounds_for_range/PlatformWindow::update_ime_position
macOS IMEYesNSTextInputClient with insertText:replacementRange: and setMarkedText:selectedRange:replacementRange:
Windows IMEYesWM_IME_STARTCOMPOSITION/WM_IME_COMPOSITION handling
Wayland IMEYeszwp_text_input_v3
X11 IMEYesXIM 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 audit

PlatformIME plumbingScreen readerVerified in Auro
Linux (Wayland)zwp_text_input_v3noneno
Linux (X11)XIMnoneno
WindowsWM_IME_*noneno
macOSNSTextInputClientnoneno

"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.

Consequences

  • Screen readers cannot inspect an Auro app. The keyboard path is the only accessible interaction Auro can claim today, and only for Button.
  • Complex-script input is expected to work through GPUI where a text element asks for an input handler, but it is unmeasured. CJK composition, dead keys, emoji pickers and input-method candidate windows are open verification items, not finished features.
  • The Phase 2 line "Accessibility (AccessKit), IME and keyboard navigation pass" is partially blocked upstream. Keyboard activation is implemented (spec 0023); AccessKit has no upstream API to call; IME has upstream plumbing but no Auro surface or verification.

When this changes

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.

Decision records

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".

Format

Every record has the same four sections:

SectionContent
StatusProposed, Accepted, Superseded by NNNN, Deprecated
Contextthe forces at play, without advocacy
Decisionone sentence, then what it implies
Consequenceswhat 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.

When to write one

Write a record when a choice:

  • is expensive to reverse (wire format, threading model, licence, dependency direction);
  • constrains future code (a rule reviewers must enforce);
  • would otherwise be rediscovered in every review thread.

Do not write one for naming a private function, choosing a test helper, or anything a Cargo.toml diff explains better than prose.

Relationship to RFCs

  • ADR - a decision that has been made, recorded after the fact.
  • RFC - a proposal that needs discussion before it is made. See rfcs/README.md.

An accepted RFC that changes the architecture produces an ADR. The RFC keeps the discussion; the ADR keeps the conclusion.

Index

#DecisionStatus
0001Tauri's app model, GPUI's rendererAccepted
0002Rust-only frontend and typed IPCAccepted
0003Capabilities at the real boundaryAccepted
0004Main thread belongs to GPUIAccepted
0005Hot reload with state preservationSuperseded by 0008
0006Dual MIT/Apache-2.0Accepted
0007No styling language in 1.0Accepted
0008Hot reload mechanism revised after feasibility spikeAccepted
0009Toolkits are the application's choiceAccepted
0010Typed events, delivered on the main threadAccepted
0011Bundling delegates to tauri-bundlerAccepted
0012Release trust: Ed25519 manifests, delegated platform signingAccepted
0013AppImage updates: in-place replacement with a backup receiptAccepted
0014Platform updates use the native installer or bundle swapAccepted
0015Restart through the app executable and a durable journalAccepted
0016Delta patches are base-bound; rollout is deterministicAccepted
0017Linux package elevation is explicit pkexec, never self-rootAccepted
0018Package rollback requires an explicit older artifactSuperseded in part by 0021
0019macOS package elevation uses an explicit AppleScript promptAccepted
0020Notarization uses a keychain profile through notarytoolAccepted
0021Opt-in rollback after a failed package applyAccepted
0022Hot reload boundary is a separate crate with a fixed frameAccepted
0023The update journal is a local trust boundaryAccepted

0001 - Tauri's app model, GPUI's renderer

Status: Accepted

Context

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.

Decision

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.

Consequences

Easier

  • The hard, unglamorous work (capabilities, packaging, updater, dev server) has a proven design to follow instead of being invented.
  • Text, IME and selection come from an editor, not from a browser.
  • There is no JS runtime, no bridge, and no second language in the app.

Harder

  • GPUI is not a stable public library the way a browser is. Upstream churn is a real, ongoing cost and the reason for the thin compatibility layer.
  • GPUI is most mature on macOS; Windows and Linux parity is the largest schedule risk.
  • Anything the web platform gives for free (devtools, CSS, a component ecosystem) has to be built or explicitly declined.

Forbidden

  • Forking GPUI. A fork dies by merge conflict; patches must stay vendored and attributable.
  • Treating the webview as the app's foundation. It is a scoped escape hatch, added in Phase 4.

0002 - Rust-only frontend and typed IPC

Status: Accepted

Context

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.

Decision

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?;

Consequences

Easier

  • A renamed command, a wrong argument type or a wrong arity is a compile error.
  • No invoke string table, no payload casing mismatches, no "command not found" at runtime.
  • The schema is generated from the same source of truth, so it cannot drift.

Harder

  • Deriving schemas requires Serialize/Deserialize/JsonSchema bounds on command arguments, which some types do not satisfy cheaply (closures, borrowed data, platform handles).
  • Commands must be registered before the app runs; there is no dynamic discovery.
  • Editors and tooling lose the "just call an endpoint" affordance a web frontend has.

Forbidden

  • A string-keyed command bus for first-party calls.
  • A second schema definition maintained by hand next to the Rust signature.
  • Hand-written serde implementations whose field names diverge from the schema.

0003 - Capabilities at the real boundary

Status: Accepted

Context

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.

Decision

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.

Consequences

Easier

  • The permission surface is small enough to audit and to document honestly.
  • Compile-time type safety covers what a runtime permission model would otherwise paper over.
  • Plugin authors get a precise denial (scope, subject, pattern) instead of a generic refusal.

Harder

  • The security story depends on the plugin host being correct, so it needs its own threat model and tests.
  • Users will ask "why can't I grant the app access to X"; the answer is "it is your code, it already has it", which must be explained rather than implied.
  • In-process plugins (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

  • Adding a capability for something first-party code can do directly.
  • A global allow-all mode that ships enabled.
  • Treating an in-process plugin as sandboxed.

0004 - Main thread belongs to GPUI

Status: Accepted

Context

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.

Decision

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.

Consequences

Easier

  • One rule to review against: if it blocks, it is not on the main thread.
  • State changes have a single ordering, which removes a class of teardown crashes in hot reload (a background task cannot outlive the entity it mutates).
  • Async commands are ordinary async fns, testable without a renderer.

Harder

  • Every cross-thread result needs an explicit hop back (cx.update / AsyncApp::update), which is more ceremony than a shared Mutex<State>.
  • Commands that are actually CPU-cheap pay a spawn for no reason; handlers must choose between direct mutation and dispatch.
  • Borrow rules: an entity borrow cannot be held across an await, so data must be cloned out first.

Forbidden

  • Blocking I/O, blocking HTTP clients, Command::output or sleep on the main thread.
  • Mutating an Entity from a worker thread.
  • A static cache of entity handles, which becomes a use-after-free when the UI cdylib is reloaded.

0005 - Hot reload with state preservation

Status: Superseded by 0008 - Hot reload mechanism revised after feasibility spike

Context

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.

Decision

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.

Consequences

Easier

  • UI iteration stops being a compile-time problem.
  • State preservation across reload makes the loop usable for real work, not just a blank window.

Harder

  • Every view must be reconstructible from serialisable state; ad hoc render-time state is lost.
  • The host and the UI library share an ABI, which must be pinned and tested across toolchains.
  • Debugging crosses a libloading boundary: symbols, breakpoints and backtraces need work.
  • Linux dlclose semantics with live threads are a known hazard.

Forbidden

  • Presenting a process restart as hot reload.
  • A reload path that leaves tasks running against the unloaded library.
  • Storing entity handles in process-global statics.

0006 - Dual MIT/Apache-2.0

Status: Accepted

Context

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.

Decision

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.

Consequences

Easier

  • Compatible with the Rust ecosystem by default.
  • Corporate adopters get a patent grant without asking for an exception.
  • No CLA, no per-contributor negotiation.

Harder

  • Two licence files must be shipped in every crate, and the workspace must not drift.
  • Vendored GPUI patches must keep their upstream licence notices.

Forbidden

  • license = "MIT" or license = "Apache-2.0" alone on any crate in the workspace.
  • Copying code with an incompatible licence into the tree.
  • A per-crate licence exception without a superseding decision record.

0007 - No styling language in 1.0

Status: Accepted

Context

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.

Decision

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.

Consequences

Easier

  • One type system, one debugger, one set of compile errors.
  • Tokens can be validated at compile time and swapped at runtime without a parser.
  • The framework cannot drift into building a CSS engine.

Harder

  • Migration guides from CSS must teach a different mental model ("thinking without CSS"), not just a syntax mapping.
  • Designers cannot hand over a stylesheet; they hand over tokens and component specs.
  • Some things CSS makes trivial (arbitrary selectors, cascade) have no equivalent and must be declined explicitly.

Forbidden

  • A .css-like file format, a selector engine, or a cascade in 1.0.
  • Adding "just a little" styling DSL behind a feature flag. That is how the rule dies.
  • Documenting a styling syntax as "planned"; it is not planned.

0008 - Hot reload mechanism revised after feasibility spike

Status: Accepted (supersedes 0005)

Context

ADR 0005 fixed hot reload with state preservation as the project bet and assumed a specific mechanism: compile UI views as a cdylib, load/swap it with libloading, and hand a serde snapshot to the new library, with a state-preserving process restart as the documented fallback.

Slice 0 of spec 0004 ran a viability spike on 2026-11-16 (Linux 7.3.4 x86_64, Wayland/niri, 12 CPUs, 22 GiB RAM, rustc 1.99.1 stable, cargo 1.99.1, debug profile, warm incremental builds, gpui = "=0.2.2", libloading = "0.8.9") to validate that mechanism before committing implementation effort.

Observed evidence:

  • Mechanics: dlopen/dlsym/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).
  • Boundary feasibility (GPUI 0.2.2): mounting UI view/render code from a separately loaded library into a host-owned GPUI application is not feasible under standard Rust/cargo builds. Window::replace_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).
  • Build cost: warm incremental rebuild of a realistic GPUI-view cdylib (trivial string change in a view) took 2m50s cargo / ~171 s wall in the spike run (full relink of a 429 MB 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.
  • Phase 0 baseline: relaunch loop save-to-visible remains ~60 s (relink-dominated), not hot reload.

Decision

Auro retains the hot-reload goal and contract from ADR 0005, but rejects the assumed cdylib/libloading view-swap mechanism for GPUI view/render code on the current stack.

  • Retained: target < 500 ms save-to-visible for a warm view-only change with preserved opted-in state (a target until measured per spec 0004 D6); a long-lived dev host that owns the GPUI application/window/event loop, runtime, managed host state, and snapshot store; versioned, opt-in serde-compatible snapshot/restore with visible resets; failed builds keep the previous UI running; failed or unsafe reloads fall back honestly and are never labelled "hot reloaded".
  • Rejected: swapping a separately loaded/unloaded 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.
  • Direction: pursue a same-process reload mechanism that keeps one GPUI/App instance and reloaded UI code in the same process and type universe (function-level/in-process hotpatching is the leading candidate to prototype, subject to OS/architecture/toolchain feasibility), or another mechanism proven to satisfy the observable contract. The selected mechanism, its layout/build model, and measured performance are recorded in spec 0004 and follow-up ADRs/RFCs as they are proven.
  • Until proven: auro 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.

Consequences

Easier

  • Implementation effort is not spent on a mechanism shown infeasible for the current renderer/API.
  • The observable contract (latency target, state preservation, honest diagnostics/fallback) stays stable while the mechanism is researched.

Harder

  • The path to < 500 ms is less certain: in-process/function-level patching is research-heavy and platform/toolchain constrained.
  • Achieving fast reload likely requires a build/layout strategy that minimises relink/patch scope for view changes, not just code splitting.
  • Specs and tooling must distinguish "reloadable change", "state-preserving restart", and "hard failure" without assuming library unload/load.

Forbidden

  • Presenting a process restart as hot reload.
  • Claiming the < 500 ms target is met without measurement recorded per spec 0004 D6.
  • A reload path that leaves tasks, callbacks, or state running against replaced/unloaded code.
  • Reintroducing cdylib swap for GPUI view code without new evidence that resolves the type/instance, mount, unload, and performance constraints recorded in spec 0004.

References

0009 - Toolkits are the application's choice

Status: Accepted (2026-11-17)

Context

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:

  1. Auro is the application layer, not a GUI toolkit. The non-goal table says widgets are GPUI's and Auro is the application framework. A component kit is a toolkit, whoever writes it.
  2. The GPUI line is pinned on purpose. 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.
  3. Size and startup are part of the pitch. The 1.0 target is a sub-6 MB hello world and sub-80 ms cold start.

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:

ProbeStripped binaryspawn → window requested (median, N=5)
Auro with its own Button15.5 MB139.8 ms
GPUI + gpui-component 0.5.0 (Root + Button)22.0 MB147.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-componentGPUI lineConsequence
0.5.1 (2026-02-05)gpui ^0.2.2last line that compiles against Auro's pinned renderer
0.6.0 and latergpui-pre ^0.3.1requires 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.

Decision

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.
  • An app adds the toolkit it wants as an application dependency, initializes it in 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.
  • Auro documents one tested integration — 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.
  • The Phase 1 proof (log viewer plus settings) uses an app-level toolkit; it does not become part of the framework.

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.

Consequences

Easier

  • No component kit in the critical path; Phase 1 focuses on the app model, typed IPC, lifecycle, events, and the dev loop.
  • The GPUI pin and hot-reload research stay untouched.
  • Apps choose the toolkit that fits them, and Auro does not have to compete with upstream widget work.
  • Auro's hello-world binary does not pay for widgets it does not use.

Harder

  • Out-of-the-box UI requires a toolkit decision; the scaffold stays deliberately minimal.
  • Docs and examples must name exact toolkit versions, because compatibility tracks the GPUI line.
  • The root/setup seam is now a public contract and cannot be removed casually.
  • Dialogs, notifications, focus rings, per-window themes and accessibility become the app's or the toolkit's responsibility, not Auro's.

Forbidden

  • Adding a toolkit to auro-core or auro-ui as a framework dependency.
  • Claiming toolkit compatibility without a pinned, tested version and a note about the GPUI line.
  • Presenting Auro's minimal Button as a component kit.

Revisit when

  • Auro plans its next GPUI line migration (after the hot-reload mechanism is settled), or
  • a toolkit reaches a stable 1.0 line that can be pinned without moving GPUI, or
  • the Phase 1 proof shows the seam is insufficient for a real application.

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.

0010 - Typed events, delivered on the main thread

Status: Accepted (2026-11-17)

Context

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:

  1. A string topic bus (Tauri's emit/listen shape). Rejected: a renamed event becomes a silent runtime no-op, which is the failure mode Auro exists to remove.
  2. GPUI's per-entity EventEmitter only. Useful for parent/child wiring, but a command has no entity and app-wide delivery would still need a fan-out mechanism.
  3. A typed event queue keyed by TypeId, with a main-thread pump. Chosen.
  4. Synchronous callbacks from the worker thread. Rejected: they would let background code mutate UI state and violate the threading contract.

Decision

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.
  • The facade installs an 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.
  • An event with no subscriber is dropped; there is no error and no fallback to a string topic.
  • Handler lists are cloned before dispatch, so a handler can emit (or cause a close/lifecycle event) without tripping a 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.

Consequences

Easier

  • Commands and views share one typed event path with no string names.
  • Events reach the UI on the correct thread without every app inventing its own channel.
  • The event type is a Rust type: renames and payload changes are compile errors.

Harder

  • A flooding producer can grow memory because the channel is unbounded; a bounded/backpressure policy is deferred.
  • Subscriptions are builder-time only; dynamic subscribe/unsubscribe needs a subscription handle and a lifetime story.
  • Cross-producer ordering is not guaranteed; apps that need it must sequence their own work.
  • Events are not persisted; a late subscriber misses earlier events.

Forbidden

  • String event names, untyped payloads or worker-thread UI mutation.
  • Treating "no subscriber" as an error; a dropped event is the documented behaviour.

Revisit when

  • A real app needs backpressure, event coalescing or ordering guarantees.
  • Dynamic subscriptions become common enough to justify a handle API.
  • Events cross the process/plugin boundary (Phase 3), where serialization and schema matter.

0011 - Bundling delegates to tauri-bundler

Status: Accepted (2026-11-17)

Context

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:

  1. Write auro-bundle from scratch. Rejected: enormous platform surface, not differentiating.
  2. Shell out to each platform's tools. Rejected: every consumer would get a different, untested path; metadata and error handling would be ad hoc.
  3. Wrap tauri-bundler behind auro-bundle. Chosen.
  4. Use 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.

Decision

auro-bundle pins tauri-bundler = "=2.10.5" and maps the validated Auro.toml [bundle] section onto its Settings.

  • The crate owns the config-to-bundler mapping, host package-type resolution and the typed AuroError::Bundle.
  • auro bundle builds the release binary and delegates artifact creation to the bundler; it does not reimplement packaging.
  • Host formats only. bundle.targets = "all" resolves to the host set; cross-compilation is not a supported Phase 2 workflow.
  • Signing, notarization, updater manifests and deltas are not claimed by this decision; later specs own those contracts.
  • Upgrading tauri-bundler is a deliberate change that must pass the three-OS CI, because a minor release may change the API.
  • Auro does not patch or fork the bundler. If a blocking bug appears, the vendoring rule and a follow-up ADR apply.

Consequences

Easier

  • Auro gains platform packaging without owning WiX, NSIS, DMG, AppImage, deb or rpm internals.
  • The app model and the packaging metadata stay one source of truth (Auro.toml).
  • The license chain remains permissive.

Harder

  • The dependency can change its API on a minor bump; upgrades are deliberate and CI-verified.
  • Auro inherits the bundler's platform limitations, tool downloads and cache behavior.
  • Signing/notarization/updater integration still needs explicit contracts and tests.
  • Debugging a packaging failure can cross into a third-party crate; the error is surfaced as AuroError::Bundle, not hidden.

Forbidden

  • Presenting a third-party bundler warning or failure as success.
  • Claiming signed/notarized artifacts before the signing spec is implemented and tested.
  • Adding a second packaging implementation without an RFC/ADR that supersedes this one.

Revisit when

  • tauri-bundler stops supporting a platform Auro targets, or its API churn becomes unmanageable.
  • Auro needs a format the bundler cannot produce (Snap/Flatpak/APK), which needs a separate decision.
  • Signing/notarization requirements outgrow what the bundler exposes.

0012 - Release trust: Ed25519 manifests, delegated platform signing

Status: Accepted (2026-11-17)

Context

Phase 2 needs two different trust problems solved:

  1. OS code signing: macOS codesign/notarization and Windows Authenticode. tauri-bundler already drives these platform tools and exposes the settings/environment hooks (ADR 0011).
  2. Update authenticity: a client must reject a manifest or artifact that was tampered with. Auro owns this format; Tauri's manifest shape is not Auro's contract.

Options for update authenticity:

  1. Reuse minisign/Tauri signature files. Rejected as the only contract: it ties Auro's manifest format to a third-party CLI and its key handling.
  2. HMAC with a shared secret. Rejected: a client that can verify can also forge.
  3. Ed25519 detached signatures over a canonical JSON payload. Chosen.
  4. Platform store signatures only. Rejected: they do not cover a cross-platform update manifest.

Decision

  • 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.
  • Auro never stores signing secrets in the repository. Unsigned bundles remain valid build outputs; signing is a configured capability, not a hard failure.
  • The updater runtime (download/apply/rollback/deltas/rollout) is explicitly not part of this decision; this ADR covers the trust format and key mechanics.

Consequences

Easier

  • A small, auditable signature format with no new service dependency.
  • Platform signing reuses the bundler and its CI/credential conventions.
  • Tests can exercise key/signature/manifest behavior without certificates.

Harder

  • Key distribution, rotation and revocation still need a client/trust contract.
  • Losing a secret key means losing the ability to publish updates accepted by clients pinned to its public key; backup/HSM policy is operational work.
  • Platform signing/notarization still requires certificates and environment secrets; the unsigned smoke tests do not prove a signed release.
  • The manifest is not yet consumed by a runtime updater, so the end-to-end update path is unproven.

Forbidden

  • Signing keys or certificates in the repository, test fixtures or logs.
  • Presenting an unsigned artifact as signed/notarized.
  • Changing manifest field names/order without a format bump and migration.

Revisit when

  • The runtime updater and rollback contract are specified.
  • Key rotation/revocation or an HSM/keychain-backed signer is needed.
  • Deltas or staged rollout change the manifest shape.

0013 - AppImage updates use in-place replacement with a backup receipt

Status: Accepted (2026-11-17)

Context

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:

  1. A generic "run this command" install hook. Rejected: it makes every app responsible for platform policy and gives the framework no way to verify rollback.
  2. A helper process that always waits for the app to exit. Deferred: it is needed for Windows and macOS, but adds a protocol before the single-file Linux case is proven.
  3. In-place replacement of a single-file AppImage, with a retained backup. Chosen for Linux.
  4. Package-manager integration for .deb/.rpm. Out of scope: it needs elevated privileges and distro-specific behavior.

Decision

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.

Consequences

Easier

  • A running AppImage can be updated safely; the old process keeps its inode.
  • Rollback is a single rename and does not depend on the release server still serving old bytes.
  • The failure mode is conservative: an unhandled receipt leaves the old file recoverable.

Harder

  • The app must manage receipt lifecycle and disk space for backups.
  • A crash before the caller discards leaves a hidden backup; there is no automatic cleanup.
  • Owner, group, xattrs and SELinux labels are not preserved beyond the copied bytes and mode.
  • Windows, macOS and package-manager updates still need their own design.

Forbidden

  • Running an installer from a generic framework hook.
  • Claiming an AppImage update is installed when the target was not replaced or verified.
  • Deleting the backup before the new version has been accepted.

Revisit when

  • Windows/macOS apply or a helper/restart protocol is specified.
  • A package-manager or delta update path changes the artifact shape.
  • A persistent receipt or rollback-on-next-launch policy is needed.

0014 - Platform updates use the native installer or bundle swap

Status: Accepted (2026-11-17)

Context

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:

  1. Run a generic command supplied by the app. Rejected: it makes platform policy invisible, cannot classify exit codes, and gives the framework no safe test seam.
  2. Add a privileged helper/restart protocol immediately. Deferred: it is needed for a full update UX, but it is a separate protocol and not required to prove the apply step.
  3. Run the native Windows MSI/NSIS installer silently, and swap a macOS .app from a staged zip. Chosen for the next apply layer.
  4. Mount macOS .dmg images or delegate to a package manager. Deferred: both need more platform setup and privilege handling.

Decision

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.

Consequences

Easier

  • Windows command construction and exit-code policy are explicit and unit-testable through a fake runner.
  • macOS replacement is filesystem-local, keeps a recoverable old bundle, and is testable on Linux.
  • There is still no generic "run this command" framework hook.

Harder

  • Windows installers may fail under UAC or because the app is running; the caller must surface that.
  • macOS .dmg/.pkg, code-signing checks, package-manager updates and restart orchestration remain separate work.
  • A crash between the two macOS renames leaves a backup and no target; a persistent apply journal is still needed.

Forbidden

  • Claiming an update is applied when the installer failed or the bundle was not swapped.
  • Building a shell command from artifact paths.
  • Automatically restarting a running app from these installers.

Revisit when

  • A helper/restart protocol or a persistent apply journal is specified.
  • .dmg/.pkg, .deb/.rpm or delta/rollout apply changes the artifact shape.
  • A Windows/macOS release needs privilege escalation or code-signing verification before install.

0015 - Restart through the app executable and a durable journal

Status: Accepted (2026-11-18)

Context

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:

  1. Ship a separate helper binary and add it to every app bundle. Rejected for now: it adds a second artifact, discovery rules and a packaging contract before the handshake is proven.
  2. Use a shell loop or a platform service. Rejected: shell construction is platform-specific and unsafe for paths; a service is a larger privilege/deployment story.
  3. Re-execute the app executable in helper mode, gated by an environment variable, and coordinate with a lock file plus a durable journal. Chosen.

Decision

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.

Consequences

Easier

  • No second executable or packaging convention is required.
  • The helper can apply and relaunch after the old process exits, avoiding an installer/app race.
  • The handoff is testable without GPUI and works on all three hosts.
  • The journal gives a durable trace of what was applied, even when the relaunch fails.

Harder

  • The app must call App::try_run/App::run for helper mode to exist.
  • The helper runs from the executable path after apply on Windows/macOS; an installer that replaces or terminates the helper needs OS-specific handling. Windows reboot requests are recorded but not scheduled.
  • The lock has a 120 s wait; a longer shutdown needs a policy.
  • Journals and backups accumulate until a later cleanup/recovery policy.
  • A crash before spawn_helper leaves a journal to inspect, not an automatic recovery.

Forbidden

  • Launching the replacement before the old process releases the handoff lock.
  • Re-entering helper mode in the replacement process.
  • Claiming a restart when the journal is not Applied.

Revisit when

  • Elevation or OS services are specified; prepared helper apply is implemented.
  • Apps need a shutdown longer than the fixed wait.
  • A journal recovery/cleanup policy is added.

0016 - Delta patches are base-bound; rollout is deterministic

Status: Accepted (2026-11-18)

Context

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:

  1. Apply a patch without verifying the base or the resulting full artifact.
  2. Pick rollout membership randomly or from unstable machine data.
  3. Put delta/rollout metadata in an unsigned sidecar.
  4. Use a custom binary patch format that only Auro can produce.

Decision

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.

Consequences

Easier

  • Operators can attach a patch and percentage to the same signed release object.
  • A bad or mismatched patch cannot become the installed artifact.
  • A support engineer can reproduce rollout membership from the key/version/hash.

Harder

  • A manifest format change requires all clients to understand v2; v1 is rejected.
  • Delta generation and storage become release-pipeline work.
  • Changing rollout percentage requires a newly signed manifest, not a server toggle.
  • Delta application needs both the old artifact and temporarily enough disk for the new one.

Forbidden

  • Trusting a delta URL or patch bytes without the signed metadata.
  • Random per-launch rollout selection.
  • Replacing the base before the full result verifies.
  • Claiming a delta was applied when the staged full artifact does not match the manifest.

Revisit when

  • A server-side rollout control plane or channels are specified.
  • Delta chains, reverse deltas or delta rollback are needed.
  • Artifact formats require a patch algorithm other than bsdiff 4.

0017 - Linux package elevation is explicit pkexec, never self-root

Status: Accepted (2026-11-18)

Context

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.

Decision

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.

Consequences

Easier

  • Package installs work on desktops with a polkit agent without making the app root.
  • Command construction stays shell-free and testable with a mock runner.
  • A failed or cancelled authorization is distinguishable from a package-manager failure.

Harder

  • pkexec, /proc and a polkit agent are runtime dependencies on Linux.
  • A held descriptor does not replace a root-owned helper for a fully hardened same-user threat model.
  • Package transactions have no Auro rollback; failures remain in the journal for diagnosis.
  • A distro that wants a narrowed policy must add a dedicated helper and policy later.

Forbidden

  • Re-executing the app as root or calling setuid.
  • A shell string, sudo, or an auto-elevated package path.
  • Relaunching after a denied or failed elevation.
  • Claiming package rollback when the package manager owns the transaction.

Revisit when

  • A root-owned helper and branded polkit policy are packaged.
  • Package rollback/downgrade, dependency repair or channels are specified.

0018 - Package rollback requires an explicit older artifact

Status: Accepted (2026-11-18)

Context

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.

Decision

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.

Consequences

Easier

  • An app that retains an old package has a tested, elevated rollback path.
  • Intent is explicit: no normal upgrade is silently reinterpreted as a downgrade.
  • The privileged command and error taxonomy stay identical to install.

Harder

  • Rollback is only possible when the caller has the older package.
  • Dependency repair and downgrade safety remain package-manager policy.
  • A failed update does not self-heal automatically; an operator or app must invoke rollback.
  • A future journal-driven rollback needs artifact retention and a policy decision.

Forbidden

  • Claiming automatic rollback when no older artifact exists.
  • Querying an unauthenticated package cache and feeding it to root.
  • Hiding a downgrade behind a normal -U/-i invocation.

Revisit when

  • Release artifact retention stores a signed previous package.
  • A package transaction policy (holds, channels, dependency repair) is specified.
  • The apply journal gains an explicit rollback plan and failure hook.

0019 - macOS package elevation uses an explicit AppleScript prompt

Status: Accepted (2026-11-18)

Context

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.

Decision

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.

Consequences

Easier

  • A signed .pkg can be applied with the standard macOS authorization sheet.
  • Command construction is testable with InstallerRunner on any host.
  • No app-wide root execution, sudo credential cache, or custom helper is required for this slice.

Harder

  • osascript and a GUI authorization session are runtime dependencies.
  • AppleScript hides the installer child's exit code; failures are classified as elevation failures.
  • The privileged installer reopens the staged path; a root-owned helper is still required for a stronger same-user threat model.
  • Notarization and package-signature policy need their own release work.

Forbidden

  • Re-executing the app as root or calling setuid.
  • Building a shell command by interpolating an unquoted path.
  • Using sudo as a silent or terminal-dependent fallback.
  • Claiming notarization or automatic rollback from this apply path.

Revisit when

  • A signed privileged helper and its installation story exist.
  • Notarization/Gatekeeper policy is specified.
  • Package rollback or a non-system install target is required.

0020 - Notarization uses a keychain profile through notarytool

Status: Accepted (2026-11-18)

Context

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.

Decision

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.

Consequences

Easier

  • Release operators can notarize with the standard macOS credential store.
  • Command construction and failure ordering are testable without Apple credentials.
  • Local auro bundle stays offline and usable without an Apple account.

Harder

  • The operator must create and maintain the keychain profile.
  • The command needs macOS, Xcode command-line tools, network and a signed artifact.
  • CI needs a secret-provisioning policy for the profile.
  • Automated integration into auro bundle and real Gatekeeper verification remain future work.

Forbidden

  • Storing an Apple ID password/API key in Auro.toml, source or argv.
  • Building a shell command from user-controlled values.
  • Reporting a release as notarized when submission or stapling failed.
  • Treating notarization as a substitute for Auro's manifest signature.

Revisit when

  • A macOS release CI with a managed keychain profile exists.
  • auro bundle gains an opt-in notarization phase.
  • Zipped .app signing/stapling policy is specified.

0021 - Opt-in rollback after a failed package apply

Status: Accepted (2026-11-18)

Context

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.

Decision

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.

Consequences

Easier

  • An app that already carries a rollback package can recover from a failed package transaction without a second app-level protocol.
  • A declined authorization does not cause a second privileged prompt.
  • The journal records the reverted outcome for the next start.

Harder

  • The apply plan and journal are larger and carry a second manifest and key.
  • A rollback package must be obtained and stored by release policy before it is needed.
  • A rollback failure leaves two diagnostics in one Failed journal.

Forbidden

  • Automatic rollback without a caller-supplied older package.
  • Treating a package cache as a rollback source.
  • Rolling back after a user declined elevation, or claiming a rollback when the package manager rejected the older package.
  • Presenting a reverted update as a successful one; the state is 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.

0022 - Hot reload boundary is a separate crate with a fixed frame

Status: Accepted (2026-11-18)

Context

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.

Decision

The generated app is a four-crate workspace:

CrateContentsMay depend on
typesViewData and the fixed HotData framenothing
datathe hot boundary view_data() -> HotDatatypes
uiRender, window, element tree, snapshot/autosaveauro, types, serde
binmain 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.

Consequences

Easier

  • Warm boundary edits are cheaper: the Linux median fell from 521 ms (N=11) to 368 ms (N=12, 325-394), and the patch library from app-sized to ~12 KB. The process, window and host state continue.
  • A mismatched data layout is a reported rejection instead of an out-of-bounds read.
  • A failed apply is a message and a still-live app, not a dead devserver listener.
  • A panic in patched boundary code is contained; the view keeps its previous values and the process survives.
  • A save outside data restarts the devserver/app and restores the snapshot; it is labelled as a restart, never as a reload.

Harder

  • The scaffold and migrations carry more crates, and adding a dependency from 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.
  • Windows remains above the 500 ms target (813 ms median, N=9) because MSVC compile/link of the boundary and bin dominates; incremental and Defender exclusions did not close the gap. The relaunch loop remains the Windows fallback.
  • macOS is measured on a shared CI runner at 509.5 ms median (N=12 after warm-up), at the target boundary; local hardware and signing remain unverified.

Forbidden

  • Adding ui -> data or data -> auro dependencies in the generated layout.
  • Changing HotData's shape without treating it as an ABI change.
  • Presenting a patch that the view rejected, or a relaunch, as a successful reload.

References

0023 - The update journal is a local trust boundary

Status: Accepted (2026-11-18)

Context

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.

Decision

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.

Consequences

  • A shared or attacker-writable journal directory is a typed error instead of a silent risk.
  • Tests that use a private temporary directory still pass; the generated app's data directory is the intended location.
  • Windows CI now executes the journal tests (private directory, junction, permissive DACL and symlink), so the Windows path is runtime-covered there; keep that leg green.
  • A Windows ancestor that can rename the private directory remains a known gap; the contract is a per-user data directory, not any path.
  • New directory components are created 0700 and files 0600 on Unix, so an umask of 000 does not silently widen the journal.
  • The updater remains opt-in. This decision is a prerequisite for a release that enables the updater, not a claim that the whole update channel is production-ready.

Specifications

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.

DocumentQuestion it answersMutability
ROADMAP.mdwhat ships in which phase, and the exit criterialiving
spec (here)what exactly must exist, with which interfaces and acceptance checksliving until the phase closes
ADRwhy a choice was made, and what it costsimmutable once accepted
RFCa design that needs discussion before it is decidedfrozen 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.

Format

Every spec carries:

  • Status - Draft, Approved, Implemented, Superseded by NNNN
  • Scope and Out of scope - the boundary is the useful part
  • Decisions - what this spec fixes, each with the alternative it rejected
  • Interfaces - types, functions, files, CLI surface, config keys, error cases
  • Acceptance - checks that prove it works, runnable by someone who did not write it
  • Open questions - what is deliberately deferred, and to where

Rules

  • A spec describes behaviour that can be verified. "It feels right" is not acceptance.
  • Examples in a spec are normative only when marked as such; otherwise they illustrate.
  • An interface change lands in the spec before it lands in code, in the same pull request.
  • Numbers (sizes, latencies, limits) are either measured or marked as a target. Never invented.
  • When implementation teaches something the spec got wrong, the spec is corrected in the same pull request that learns it.

Index

#SpecPhaseStatus
-What Auro takes from Taurievidenceliving
0001Foundation: workspace, runtime seam, commands, state, dev loop0Implemented
0002Auro.toml schema, merge rules, validation0Implemented
0004Hot reload: save-to-visible with preserved state, measurability, mechanism under revision1, 3Draft - 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)
0005Toolkit seam: setup hook, app-owned root, no framework toolkit1Implemented
0006Lifecycle events: ready, window open/close, exiting1Implemented
0007Typed application events: sender, main-thread pump, handlers1Implemented
0008Command schemas: input/output metadata on the handler1Implemented
0009Window manager: open/close/focus by configured label1Implemented
0010Bundling: map [bundle] to tauri-bundler, host formats, auro bundle2Implemented (Linux, Windows and macOS verified)
0011Signing keys, artifact hashes, platform signing config2Implemented
0012Signed update manifests: format, verify, CLI2Implemented (v2; 0013 stage, 0028 deltas/rollout)
0013Updater runtime: check, download, verify and stage2Implemented (full/delta; 0014/0025 apply)
0014AppImage apply: atomic replacement and rollback receipt2Implemented (Linux only)
0015Single instance: advisory lock, argument forwarding2Implemented (opt-in activation helper)
0016Capability manifests and enforcement2Implemented (host wiring pending)
0017Autostart service2Implemented
0018Notifications service2Implemented
0019Keychain service2Implemented
0020Global shortcuts service2Implemented (pressed callbacks)
0021Tray service2Implemented (icons, menus and click callbacks)
0022Deep links: scheme registration, parsing and queue2Implemented (initial and forwarded wiring)
0023Keyboard activation for Button2Implemented (AccessKit/IME pending)
0024Alpha release: version, publish order, facade features, scaffold2Draft (alpha candidate; publication pending)
0025Windows installer execution and macOS .app replacement2Implemented (.dmg and macOS elevation separate)
0026Update journal and restart helper2Implemented (helper applies, relaunches, reconciles)
0027Linux .deb/.rpm package apply2Implemented (elevation in 0029)
0028Binary deltas and deterministic staged rollout2Implemented
0029Linux package elevation through pkexec2Implemented
0030Linux package rollback with an explicit older artifact2Implemented (manual policy)
0031macOS .pkg apply through installer/osascript2Implemented in tree (runtime unverified)
0032macOS notarization submission and stapling2Implemented in tree (credentials/runtime unverified)
0033Update journal trust boundary: fail-closed ownership/mode/ACL checks2Implemented (Unix tested; Windows compile-verified, runtime unverified)

What Auro takes from Tauri

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.

Verdict per crate

CrateReusable?Why
tauri-bundlerYes, as a dependencyNo 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-signYes, laterCodesign/notarize helpers with no webview involvement (crates/tauri-macos-sign)
tauri-utilsShape onlyWebview-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-macrosShape onlyEmits 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-runtimeNoNot 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-wryNoIt is the webview (pub use wry, src/lib.rs:98)
tauri-codegenNoEmbeds assets, hashes/compresses them, injects CSP (crates/tauri-codegen) - all webview concerns
tauriNowry is a default feature (crates/tauri/Cargo.toml:185-192); PlatformWebview exposes the raw webview (src/webview/mod.rs:153-195)
tauri-cliShape onlyIts command set and dev flow are the reference; the code is tied to tauri-build/tauri-codegen
tauri-pluginShape onlyPlugin builder/hooks are generic enough to imitate

What we copy as shape

TauriAuroNote
#[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 / InvokeErrorsame names, our traitsJSON 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>sameState 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 resolutionsame file format and resolution ideaScopes stay data; enforcement stays at the call site
bundle_project(&Settings)auro_bundle::bundle(&Config) mapping into that callOur config stays ours; the mapping is one module

What the Tauri study changes in our plans

  1. No runtime crate to reuse. 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.
  2. Bundling is not the place to be original. Mirroring tauri-bundler's Settings and its per-OS tool matrix (codesign/dmg, WiX/makensis, AppImage/deb/rpm) buys years of edge cases.
  3. MSRV floor becomes 1.90. 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).
  4. The bundler is not SemVer-stable. Its own docs say minor releases may add fields and change or remove error variants (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.
  5. Version window. crates.io carries 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.

GPUI findings that constrain the spec

Studied gpui 0.2.2 (crates.io, 2026-10-30), edition 2024, license Apache-2.0, no declared rust-version.

  • The public API is 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.

Dev loop and build-time shape

  • 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).
  • Asset embedding lives in 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 consequence: there is no "static server" or "frontend dist" step to imitate. 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.

Capabilities shape (ACL)

Tauri's ACL is separable from the webview, and Auro keeps its file format and resolution model.

  • Capability file fields: 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.
  • Discovery is directory-based: 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.
  • Permission files declare 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.
  • Resolution happens at build time, producing 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.
  • App-level commands are not gated by a capability in Tauri; only plugin commands are. That is the same boundary Auro already decided on.

Deliberately not copied

  • The webview escape hatch, CSP injection, asset embedding and code signing of web assets.
  • 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.
  • Mobile targets. Tauri 2 supports them; Auro does not claim to.

0001 - Foundation

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.

Scope

  • A Cargo workspace with the crates needed for the slice, and only those.
  • Auro.toml: the configuration surface an app author edits (fields in 0002).
  • auro new, auro dev, auro build, auro doctor.
  • A typed command contract: #[auro::command], generate_handler!, AuroError.
  • Application state, reachable from commands and views (app-wide events arrive with the Phase 1 lifecycle work).
  • The GPUI seam: how Auro owns the main thread and hands the renderer a view.
  • The generated project skeleton.

Out of scope

  • Plugins, capabilities enforcement, bundling output, updater, signing - later phases, later specs.
  • Hot reload. Phase 0 relaunches the process; the < 500 ms target and mechanism are tracked in spec 0004.
  • A component kit. Phase 0 ships the primitives the slice needs, styled by tokens.
  • App-wide events and lifecycle management. Both arrive in Phase 1 with the window manager.
  • Embedded config, embedded assets, $schema generation and build-script codegen. Config loads at runtime until the bundler lands.
  • Mobile.

Decisions

D1 - Six crates now, eleven in the full graph

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.

CrateKindDepends onResponsibility
aurolibcore, ui, ipc, macrosApp builder, window attachment, prelude; the only crate an app depends on
auro-corelibipcconfig loading, state store; re-exports the IPC runtime; no renderer types (lifecycle and events in Phase 1)
auro-ipclib-CommandArg, IpcResponse, Invoke, registry, AuroError, tokio runtime bridge
auro-macrosproc-macro-#[command], generate_handler!
auro-uilibcorethe only crate that names gpui; primitives, tokens, Render re-export; themes are toolkit-owned (ADR 0009)
auro-clibincorenew, 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.

D2 - GPUI is pinned exactly

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.

D3 - Two executors, one bridge

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:

  • Views, entities and window state are !Send and never cross threads.
  • Command arguments and return values are Send + 'static; results come back through Entity::update / AsyncApp::update, then cx.notify() schedules the repaint.
  • Any 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.

D4 - Commands are Rust functions with an attribute

#![allow(unused)]
fn main() {
#[auro::command]
async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> { /* ... */ }
}
  • Attribute options: 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.
  • Arguments: 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: 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.
  • The first-party call site is a plain function call (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.

D5 - State is owned, never borrowed across threads

  • 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.
  • Views read state through the app handle; one owner per piece of state.
  • App-wide notifications are a typed enum in 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.

D6 - Configuration

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.

  • Config is authoritative for identity and windows. 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().
  • Discovery, in order: 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.
  • CLI overrides travel to the child process as 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.

D7 - The dev loop relaunches

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.

D8 - Bundling is delegated

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.

D9 - Window keys are honored where GPUI can express them

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.

Interfaces

CLI

CommandBehaviour
auro new <path>scaffold the tree below; refuse a non-empty directory
auro devbuild, spawn, watch, relaunch
auro buildcargo build --release; no packaging until Phase 2
auro doctortoolchain, GPUI pin, config parse result, platform, Linux dependencies, and config keys the platform cannot honor
auro --versionthe workspace version

Generated project

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.

The slice, as the author writes it

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.

Acceptance

Runnables, in order, on a clean checkout:

  1. cargo build --workspace --locked succeeds on Linux, macOS and Windows.
  2. cargo run -p auro-cli -- new /tmp/demo creates the tree; cargo check inside it passes.
  3. 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.
  4. Ctrl-C during auro dev leaves no child process behind.
  5. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked pass.
  6. Unit tests cover: config parse, platform merge, unknown-key rejection, State extraction, sync and async dispatch through CommandHandler, AuroError conversion, and auro new refusing a non-empty directory.
  7. One headless test in the app crate: start Auro's runtime, render the root view through 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.
  8. Save-to-window time is measured once and recorded here. No target is claimed until measured.

Status (2026-11-15, closed 2026-11-17)

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.

  • 1: met in CI. CI is green on macOS, Windows, 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.
  • 2: met locally (/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.
  • 3: met. Window opens and the rebuild/relaunch cycle work locally; a headless GPUI test clicks the button, dispatches the async #[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.
  • 4: met locally (Ctrl-C exits 0, no orphan).
  • 5: met locally (fmt, clippy -D warnings, tests).
  • 6: met (config parse/merge/unknown-key refusal, State extraction, sync and async dispatch, rename/unknown-command handling, AuroError conversion via ? for io and json, auro new refusing a non-empty directory).
  • 7: met. 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.
  • 8: met (measurement recorded). A saved source change to a visible relaunch measured ~60 s on the development machine (relink dominates; the watcher itself reacts once per edit). This is the gap hot reload must close, not an acceptable steady state. Re-measured 2026-11-16 on the scaffold demo with the traced dev loop (debug, warm dependency cache, incremental relink): save→build 2380 ms, save→repaint-requested 2730 ms (medians over three saves; 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.

Open questions

QuestionWhere it settles
Component kit: own primitives vs gpui-componentResolved: Auro ships no toolkit; the app chooses one (ADR 0009, spec 0005)
Hot reload mechanism and its measurabilitySpec 0004
Plugin isolation: out-of-process first or in-processPhase 3 RFC
Does release embed config or ship Auro.toml next to the binaryPhase 2 spec
Windows/Linux input, IME and a11y parityPhase 2 audit

0002 - Configuration

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.

Decisions

D1 - TOML, kebab-case, next to the crate manifest

  • File: Auro.toml at the app crate root, beside Cargo.toml.
  • Keys: 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.
  • Unknown keys are errors, not warnings. A typo in a config file must not silently do nothing.

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.

D2 - Load order and overrides

  1. 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.
  2. Auro.<platform>.toml where platform is macos, windows or linux, merged key by key.
  3. 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.

D3 - Windows are a list

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.

Schema

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]

KeyTypeDefaultNotes
identifierstringrequiredreverse-DNS, [A-Za-z0-9.-], no leading/trailing dot; becomes the bundle id
product-namestringrequiredwindow-title default and bundle display name
versionstringrequiredSemVer; must match Cargo's concrete package.version (including version.workspace = true) or the build fails
descriptionstring""one line, used by the bundle metadata
authorsarray of string[]"Name <email>"
homepagestring""URL
licensestring""SPDX expression; must be compatible with MIT OR Apache-2.0
default-windowstringfirst window's labelmust match a declared label

[[app.windows]]

KeyTypeDefaultNotes
labelstringrequiredunique, [A-Za-z0-9_-]
titlestringapp.product-name
widthinteger960logical pixels
heightinteger640logical pixels
min-widthintegernone
min-heightintegernone
max-widthintegernone
max-heightintegernone
resizablebooltrue
decorationsbooltrue
transparentboolfalse
always-on-topboolfalse
visiblebooltrue
centerbooltrue
fullscreenboolfalse
theme"light" | "dark" | "system""system"

[dev]

KeyTypeDefaultNotes
watcharray of string["src", "Auro.toml"]paths relative to the app dir
run-argsarray of string[]passed to the spawned binary in relaunch mode; dx owns the process in hot mode and auro dev prints a note
build-argsarray of string[]passed to cargo build
hotboolfalserun 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.

KeyTypeDefaultNotes
activebooltrue
targetsarray 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
iconarray of string[]first existing format wins per platform
resourcesarray of string[]glob patterns, relative to the app dir
categorystring"DeveloperTool"Apple/XDG category name
short-descriptionstring""installer metadata
long-descriptionstring""
copyrightstring""
license-filestring""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.

KeyTypeDefaultNotes
signing-identitystringnonepassed to codesign
entitlementsstringnoneplist path relative to the app dir
hardened-runtimebooltruedistribution default
skip-staplingboolfalsedo not wait for/stapling the notarization ticket
notarize-profilestringnonexcrun 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.

KeyTypeDefaultNotes
certificate-thumbprintstringnoneSHA-1 of the signing certificate
digest-algorithmstringnonee.g. sha256
timestamp-urlstringnonetimestamp server
tspboolfalseRFC 3161 timestamping
sign-commandstringnonecustom signer; %1 in sign-args is the binary
sign-argsarray of string[]arguments for sign-command
allow-downgradesbooltrueallow an older version to replace a newer one

webview-install-mode is not configurable: Auro has no webview and always skips WebView2.

Validation

Failures are AuroError::Config { path, key, message } and abort before a window opens. Rules:

  1. Unknown key: reported with the key path and the closest known key, if any.
  2. Wrong type or missing required key: reported with the key path.
  3. 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.
  4. Duplicate window labels, or default-window naming nothing: error.
  5. 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.
  6. Relative watch, icon, license-file, resources or bundle.macos.entitlements paths escaping the app directory: error.
  7. Window 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.
  8. A window declared in app.windows without a matching App::root/App::root_with is a typed AuroError::Window before the event loop starts, not a headless process.

Interfaces

# 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>;
}

Acceptance

  • The smallest valid file parses; every default in the tables above is the value the app uses where the platform can express it. auro doctor lists the keys the current platform cannot honor.
  • A missing Auro.toml fails with exit code 2 and a message naming the paths searched.
  • An unknown key under [app] fails with a message naming it.
  • Auro.linux.toml overriding app.windows replaces the list; overriding app.product-name changes only that key.
  • A version mismatch against Cargo.toml fails auro build and auro dev.
  • Round-trip test: every documented key is set to a non-default value, serialized back, and equals the original.

Status (2026-11-17)

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.

0004 - Hot reload

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.

Slice 0 viability spike (2026-11-16)

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:

AreaObservation
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 boundarySwapping/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 safetyA 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).

Option 1 consolidation spike (2026-11-16)

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).

CaseObservation
Plain Rust (non-GPUI) HotFn patchrev=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 retroactivePatches 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/resetBefore: 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 + recoveryBroken 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 workTicker-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 changeAdded Vm field with coordinated construct/log/UI update in same edit: visible (362 ms), extra logged, counter progressed, no error.
s9 multi-module tip crateBaseline 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/devservercargo 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 pathFailed 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:

ObservationEvidence
Patch transport is soundapply_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 causethe 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 crashesHotFn::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, repeatedlyHotFn::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 valuesboundary 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 frameworkthe 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.

Scope

  • The auro dev hot-reload flow: watch, build, apply reload or fallback, and user-visible reporting.
  • The host/reloadable-UI boundary for development: process ownership, reload unit, and compatibility contract.
  • Snapshot, restore, and invalidation of state across a reload or state-preserving restart.
  • Reload eligibility: which source changes may reload in-process and which must restart.
  • Failure handling: build errors, incompatibility/apply errors, restore errors, panics, and cancellation/rollback.
  • Measurability: the definition and recording of save-to-visible latency.
  • Staged delivery from experimental hot reload (Phase 1) to GA with state preservation (Phase 3).

Out of scope

  • Shipping hot updates to released binaries (auro-update, Phase 2). This spec covers the dev loop only.
  • Hot reload of plugins or out-of-process plugin hosts (Phase 3), except stating that plugin reloadability is a separate contract.
  • Requiring a specific patching/swap technology. The required contract is observable reload/restore behaviour and measured latency, not a named technique, until a mechanism is proven and recorded here.
  • Mobile targets.
  • Preserving state that is inherently non-serialisable or external (open sockets, OS handles, unmanaged threads, GPU resources owned outside the snapshot contract) except making loss visible.
  • A stable cross-compiler or cross-version reload ABI for third parties in 0.x.

Baseline (measured)

PathObservedNotes
Phase 0 relaunch (auro dev)~60 s save-to-visibleDevelopment 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 rebuild2m50s cargo / ~171 s wallDebug, 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.

Decisions

D1 - Long-lived dev host, same-process reload (subsecond/dx, experimental)

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:

CrateContentsDepends on
typesthe decoded ViewData and the fixed HotData framenothing
datathe hot boundary view_data() -> HotDatatypes
uiRender, window code, the element tree, snapshot/autosaveauro, types, serde
the binmain 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.

D2 - Host-stable and reloadable code have an explicit boundary

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.

D3 - State survives as a versioned, opt-in snapshot

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).
  • a build/session identity sufficient to diagnose mismatches (e.g. build id/hash of the reload unit).
  • per-entry payloads: a stable key, an entry version, and serialized bytes (the canonical encoding is serde-compatible; the wire encoding is fixed at implementation time and recorded here).

State categories:

CategoryOwnerReload behaviour
View/UI state explicitly marked restorableReloadable UI, via snapshot contractSerialized 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 unitHostPreserved 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 inReloadable UIReset on reload/restart. Reset must be visible in dev diagnostics, not silent.
External/non-serialisable resourcesOS/runtimeRecreated 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.

D4 - Successful reload, failed build, and fallback are distinct outcomes

OutcomeConditionHost behaviourUser-visible label
Hot-reloadedReloadable 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 failedA boundary build/patch compilation failsKeep previous UI active and interactive; do not apply a partial reloadcompiler/build diagnostics; “previous UI still running”
Host restart, rebuild failedA host-code save restarted the devserver and its rebuild failsKeep 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, recoveredBuild/patch succeeds but compatibility/apply/restore fails and previous UI remains valid or can be safely rolled backKeep or restore previous UI as applicable; do not present as reloadedexplicit failure reason
State-preserving restart (fallback)Reload cannot be completed safely, or a configured/required restart change occurredRestart 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 failureRestart/restore impossibleExit non-zero with diagnosticerror

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.

D5 - Compatibility is enforced, not assumed

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.

D6 - Measurability

“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:

  • machine/OS, CPU class, storage class (if relevant), debug/release, warm/cold incremental state;
  • what changed (view-only, style/token, command signature, config, dependency) and file count;
  • whether the outcome was hot-reloaded, reset entries, or fallback restart;
  • median, p95 and spread over N >= 10 edits after warm-up (or an explained smaller N). The current trace separates watcher→devserver (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.

D7 - Reload eligibility and staged delivery

Not every edit is safely reloadable in-process. The dev loop classifies changes:

Change classExpected pathNotes
Reloadable UI/view code and resources within the supported reload unitHot-reloadPrimary path; must preserve opted-in state per D3.
Host-stable/bootstrap code, host dependency graph, toolchain/config affecting host/runtime compatibilityState-preserving restart or full restartClassified and reported; never a silent no-op.
Auro.toml / window-identity changesReload config in host where safe; otherwise restart with explanationMust not corrupt running host assumptions.
Compatibility/build identity mismatch after rebuildReload 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):

  • Experimental (Phase 1): opt-in hot reload in 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.
  • GA (Phase 3): default dev experience for supported apps; documented state contract stable enough for third-party app authors; measured latency published per platform tier; CI/perf-budget integration as the budget becomes enforceable.

Rejected: enabling an unsafe/undefined reload path by default. Rejected: declaring GA without measured D6 evidence for the documented case.

Interfaces

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.

CLI (auro-cli)

SurfaceBehaviour
auro devDefault 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/statusCtrl-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.
DiagnosticsBuild 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)”.

Configuration (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):

  • A dev setting to enable/select hot reload mode (experimental opt-in).
  • Watch/build inputs sufficient to distinguish host-stable and reloadable rebuilds, or an explicit documented convention derived from project layout/mechanism.
  • Optional dev settings for snapshot/fallback behaviour if needed (e.g. restart-on-reload-failure policy) - only if they change observable behaviour; otherwise internal.

Any new key is added to spec 0002, validation, and auro doctor in the same change that implements it.

Application / runtime API (auro, auro-core, auro-ui, auro-ipc)

  • A way to declare reloadable roots/views and their stable snapshot identity.
  • A snapshot/restore hook for opted-in view state (trait or callback), invoked only on the main thread with host-provided serialization context.
  • A host-visible distinction between host-stable managed state and reloadable-UI-owned state, so reload safety (D2, D3, D5) can be enforced or diagnosed.
  • Teardown/cancellation/invalidation integration so reloadable tasks and subscriptions cannot run against replaced code after reload.

Illustrative (non-normative):

pub trait ReloadSnapshot: serde::Serialize + serde::de::DeserializeOwned {
    const SNAPSHOT_KEY: &'static str;
    const SNAPSHOT_VERSION: u32;
}

Reload mechanism contract (to be defined by prototype)

The implementation must define and record a mechanism-specific contract covering, at minimum:

  • build identity and compatibility checks performed before apply;
  • how updated UI code is applied in the same GPUI/App process;
  • snapshot capture/restore ordering and rollback on failure;
  • teardown/quiesce of reloadable tasks, callbacks, and subscriptions;
  • diagnostics for incompatibility, apply failure, and reset state.

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.

Generated project layout

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:

  1. Split it into a workspace with a thin bin, 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.
  2. Put the changing values in data::view_data() -> HotData and call ui::run(data::view_data) from main. The view decodes the frame; the boundary never constructs GPUI types.
  3. Add [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".
  4. Set [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.

Acceptance

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.

  1. Reload correctness (headless where feasible): a host test harness mounts/runs a reloadable UI fixture, applies a state mutation, applies a newly built fixture with changed view output, and asserts opted-in state is restored and the new output is observable. A fixture whose snapshot version/key is incompatible resets only the affected entry and reports a visible reset diagnostic.
  2. Build failure keeps UI live: with a running UI, an intentionally failing rebuild leaves the previous UI active and interactive; diagnostics are surfaced; no broken reload is applied.
  3. Reload failure safety: a compatibility/apply/restore failure does not crash the host; the outcome follows D4 and is labelled (previous UI retained/rolled back or explicit state-preserving restart).
  4. No replaced-code execution: teardown/invalidation prevents reloadable tasks/callbacks from running against replaced code after apply/rollback (verified by a fixture that would otherwise touch stale state; test fails if invoked).
  5. Fallback honesty: a forced fallback restart restores snapshot state when possible and is reported as “restarted (state restored/reset)”, never as “hot reloaded”.
  6. Measurability: in hot-reload mode the dev session emits timing/trace data sufficient to compute save-to-visible per D6; at least one measured run is recorded in this spec (or linked artefact) with machine, method, N, median, p95, and outcome class before experimental mode is described as meeting any latency target.
  7. CLI/dev integration (manual/platform where needed): 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.
  8. Documentation and gates: 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.

Open questions

QuestionWhere 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 viablePartially 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 layoutImplementation of this spec; recorded here when chosen
Canonical snapshot encoding (JSON, CBOR, postcard/bincode-class) and compatibility policyImplementation; must remain serde-compatible at the API boundary
How managed State<T> participates when its type is defined in reloadable code vs host-stable codeImplementation + 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 mechanismImplementation, per platform notes
In-app surfacing of build/reload diagnostics (overlay/panel) vs terminal-only in experimental modeauro-ui/dev UX follow-up; terminal reporting is the minimum
Windows and macOS feasibility, code-signing implications, and debugger behavior for the chosen mechanismPartially 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 pathImplemented (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

0005 - Toolkit seam

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.

Scope

  • 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().
  • The default App::root stays as the Default-only sugar.
  • The config handoff that lets an app apply app.windows[].theme to its toolkit.
  • Documentation of one tested integration (gpui-component 0.5.x with GPUI 0.2.2).

Out of scope

  • Any component toolkit, component implementation, component tests or toolkit compatibility guarantee beyond the documented line.
  • Auro-owned themes or a theme system.
  • Per-window toolkit theming, dialogs, notifications, focus management: the toolkit owns them.
  • Loading a toolkit through a plugin; this is a normal application dependency.

Decisions

D1 - The framework owns no toolkit

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.

D2 - Setup runs once, before windows

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.

D3 - The app can own the window root

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.

D4 - Windows keep their existing contract

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.

D5 - Config is the only handoff

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.

D6 - One tested integration, versioned honestly

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.

Interfaces

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.

Acceptance

  1. A setup closure runs once, in registration order, before any root builder; a headless test records the order (app::tests::setup_runs_before_roots_and_root_with_uses_the_app_builder).
  2. 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.
  3. root keeps its existing behavior; the window-title and window-options tests cover the shared opener.
  4. Config reaching setup includes the declared theme; auro doctor reports a non-system theme as toolkit-owned.
  5. 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.
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, and cargo test --workspace --locked pass.

Open questions

QuestionWhere it settles
Whether to publish an optional auro-gpui-component integration crateAfter the next GPUI line migration; ADR 0009 keeps the core toolkit-free meanwhile
How per-window themes map onto a toolkit with a global themeApp-level decision documented by the app; Auro passes the config through
Whether an optional toolkit integration should provide a shared theme bridgePhase 3, if more than one toolkit needs it

0006 - Lifecycle events

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.

Scope

  • A typed LifecycleEvent enum in auro-core.
  • App::on_lifecycle handlers, run on the main thread.
  • Window-opened, window-closed and ready/exiting ordering for windows declared in Auro.toml.
  • Tracking the window handles Auro opened so a close can be attributed to a label.

Out of scope

  • A user-defined app event bus. The generic typed event bus is the next core slice.
  • Runtime window opening, closing or focusing by label (WindowManager).
  • Cancelling exit. Exiting is informational in Phase 1.
  • Focus, resize, move and platform lifecycle events.
  • macOS/Windows-specific termination (Cmd-Q, session end) beyond the GPUI close path.

Decisions

D1 - The event is a closed, typed enum

#![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.

D2 - Handlers are main-thread and ordered

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.

D3 - Order

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.

D4 - Only Auro-opened windows are tracked

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.

D5 - Exiting is informational

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.

D6 - No lifecycle state crosses threads

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.

Interfaces

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.

Acceptance

  1. A headless test opens a configured window and records WindowOpened { label } before Ready; the root builder runs after setups (app::tests::setup_runs_before_roots_and_lifecycle_reports_ready).
  2. Lifecycle handlers run in registration order; the same test records two handlers.
  3. WindowClosed and Exiting dispatch to handlers and preserve payloads (app::tests::lifecycle_reports_window_close_and_exit).
  4. The opened handle is tracked for close attribution; the first test asserts one tracked handle.
  5. A real app with a lifecycle handler logs 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.
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Generic user-defined app event bus, background-to-main deliveryNext core spec
Runtime WindowManager: open/close/focus by label; extend the registryPhase 1 window spec
Cancellable ExitRequested and platform termination eventsLater lifecycle spec
Focus/resize/move events and per-window subscriptionsAfter the window manager
Whether lifecycle handlers should receive &Config or a window handleRevisit with the window manager

0007 - Typed application events

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.

Scope

  • EventSender: a cloneable, Send + Sync producer handle in auro-core.
  • The 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.
  • The facade pump that delivers background events on the GPUI main thread.

Out of scope

  • Dynamic subscribe/unsubscribe after startup.
  • Backpressure, coalescing, persistence or replay.
  • String topics and untyped payloads.
  • Cross-process/plugin events (Phase 3), which need serialization and a schema.
  • A total ordering across producers.

Decisions

D1 - Events are Rust types

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.

D2 - Two producer paths

  • Main thread: emit(event, cx) dispatches synchronously to the registered handlers. Use it from a view or lifecycle handler.
  • Any thread: 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.

D3 - Delivery is main-thread and ordered per producer

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.

D4 - Handlers

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.

D5 - No backpressure in this slice

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.

Interfaces

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.

Acceptance

  1. A main-thread emit reaches the handler for its type and not the handler for another type (app::tests::delivers_typed_events_and_keeps_types_isolated).
  2. A background 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).
  3. App::new manages an EventSender in the state store; the test obtains it with State<EventSender>.
  4. An event with no subscriber is dropped without panic (covered by type isolation emitting an unhandled type).
  5. A real app emits from a command and updates the view from the handler; recorded in the pull request with the run environment. The pump path is otherwise covered by the queue/dispatch test.
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Backpressure/coalescing for hot producersLater event-policy spec
Dynamic subscriptions with a handle/tokenWhen a real app needs runtime subscribe
Cross-process/plugin event serialization and schemaPhase 3 plugin spec
Whether lifecycle events should also flow through on_eventKeep separate: lifecycle is a closed enum with a different ordering contract
Event ordering across producersApp's responsibility; revisit if a framework primitive needs it

0008 - Command schema registry

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.

Scope

  • schemars 1.x as the schema source.
  • #[auro::command] derives the input/output schema from the signature.
  • CommandHandler stores and exposes per-command schemas.
  • Input schema composition for the command's non-state arguments.

Out of scope

  • Wiring the registry into App or auto-generating docs from it (the handler remains a boundary for plugins).
  • Plugin transport and schema negotiation (Phase 3).
  • Schema evolution/versioning policy.
  • JSON Schema $id and remote references.
  • Serializing State<T> values; state is resolved, not sent.

Decisions

D1 - The macro owns schema derivation

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.

D2 - Input is one object schema

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.

D3 - Output is the Ok type

For 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.

D4 - Metadata is additive on the handler

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().

D5 - The schema is a JSON value, not a live generator

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.

Interfaces

#[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>;
}
}

Acceptance

  1. A command with a primitive argument stores an input schema with that property under properties, listed in required; an Option<T> argument is not listed in required.
  2. State<T> arguments do not appear in the input schema.
  3. rename_all = "camelCase" changes the property key.
  4. The output schema is derived from the Ok type; () becomes a null schema.
  5. A manually registered command remains dispatchable and has no schema entry.
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Wiring the registry into App and generated docsPlugin/docs slice
Schema negotiation, versioning and compatibilityPhase 3 plugin spec
Definition-name collisions when two types share a nameRevisit when struct args are used in the wild
Optional command argumentsLater command-contract change
$id and cross-file referencesNot planned for 1.0

0009 - Window manager

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.

Scope

  • A main-thread window manager installed by App::run.
  • open, close, focus, is_open and handle by configured label.
  • Interaction with LifecycleEvent::WindowOpened / WindowClosed / Exiting.
  • A typed error for an unknown label or a missing root.

Out of scope

  • Creating a window that is not declared in Auro.toml.
  • Multiple simultaneous instances of one label.
  • Window position/size persistence, modal parents, focus/resize events.
  • Preventing close or exit; the lifecycle contract stays informational.
  • Platform-specific window controls beyond what GPUI exposes.
  • Managing windows that the app or a toolkit opened directly through GPUI.

Decisions

D1 - The label is the identity

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.

D2 - The manager is installed at run

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.

D3 - Open

windows::open(label, cx):

  • unknown label -> AuroError::Window { label, message };
  • label declared but no root attached -> the same typed error;
  • already open -> returns the existing handle, does not create a second window and does not emit a second WindowOpened;
  • otherwise builds the root through the registered builder, records the handle, emits LifecycleEvent::WindowOpened { label } and returns the handle.

Opening does not focus the window unless the root/GPUI does so; focus is explicit.

D4 - Close

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.

D5 - Focus and queries

  • 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.

D6 - Startup is unchanged

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.

Interfaces

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.

Acceptance

  1. Opening an undeclared label returns AuroError::Window; opening a declared label with no root returns the same type.
  2. Opening twice returns the same handle and emits WindowOpened once.
  3. Closing an open window removes it and emits WindowClosed; closing the last window emits Exiting through the existing close observer.
  4. Reopening a closed configured window works and emits WindowOpened again.
  5. focus returns true for an open window and false otherwise; is_open/handle agree with cx.windows().
  6. A real app opens and closes a second configured window from a lifecycle handler; recorded in the pull request with the environment.
  7. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Focus/resize/move events and per-window subscriptionsAfter this slice
Window position/size persistence across runsPlatform-services slice
Modal parent/child relationshipsPlatform-services slice
Preventing close or exitLater lifecycle spec
Multiple instances of one label (e.g. an untitled document window)Needs an instance id, not a label; later

0010 - Bundling

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).

Scope

  • The auro-bundle crate: config-to-bundler mapping and artifact paths.
  • The auro bundle CLI command: release build, then bundle.
  • Host formats: macOS app/dmg, Windows msi/nsis, Linux appimage/deb/rpm.
  • Mapping of identity, descriptions, license, category, icons and resources.
  • Typed errors (AuroError::Bundle).

Out of scope

  • Code signing, notarization and the signed updater (later Phase 2 specs).
  • Cross-compilation as a supported workflow; the bundler warns and is not exercised by CI.
  • Custom installer UI, installer hooks and file associations.
  • Generating icon assets beyond the scaffold's placeholder; apps provide their own through [bundle].icon.
  • Package formats outside the config schema (APK, Snap, Flatpak, …).

Decisions

D1 - Delegate to tauri-bundler, pinned exactly

tauri-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.

D2 - The config is the only input

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.tomltauri-bundler
app.identifierBundleSettings::identifier
app.product-namePackageSettings::product_name
app.versionPackageSettings::version
app.descriptionPackageSettings::description (product name when empty)
app.authors / app.homepagePackageSettings fields; homepage also in bundle settings
app.licenseBundleSettings::license
bundle.categoryBundleSettings::category (AppCategory)
bundle.short-description / long-descriptionbundle settings
bundle.copyright / license-filebundle settings
bundle.icon / resourcesabsolute paths derived from the app directory
bundle.targetsPackageType list; "all" uses the host set

An unknown category or package format is AuroError::Bundle, not a bundler panic.

D3 - auro bundle builds first

auro 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.

D4 - Host formats only

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.

D5 - Signing is not claimed yet

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.

Interfaces

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".

Acceptance

  1. Explicit targets map to the requested PackageTypes; "all" maps to the host set (auro-bundle unit tests).
  2. The manifest metadata reaches the bundler settings: identifier, icons, binary name, category, output directory, and package types (maps_the_manifest_metadata).
  3. An unknown category is a typed bundle error, not a panic (rejects_an_unknown_category).
  4. 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).
  5. 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.
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Status (2026-11-17)

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.

Open questions

QuestionWhere it settles
Codesign/notarization and Windows signingmacOS notarization and signing spec
Package-manager apply and restart/rollback orchestrationLinux packages, elevation; deltas/rollout are spec 0028
Icon placeholders in the scaffoldBundling follow-up; apps may supply icons today
Cross-compilationNot planned for 1.0; revisit if demand appears
AppImage tool downloads and offline buildsDocument the bundler's cache/tooling behavior

0011 - Signing and release keys

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).

Scope

  • 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>.
  • The config-to-signing mapping for macOS codesign/hardened runtime/entitlements and Windows Authenticode fields.

Out of scope

  • Provisioning Apple Developer or Windows Authenticode certificates.
  • Storing keys in a platform keychain; the initial contract is a 0600 key file.
  • A signing service or HSM.
  • Notarization credentials in the repository; they remain environment variables.
  • Runtime updater download/apply (the runtime is spec 0013 and spec 0014 and 0025; package-manager apply remains separate).

Decisions

D1 - Ed25519 keys, base64 text files

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.

D2 - SHA-256 for artifacts

auro-sign::sha256_file produces lowercase hex. Manifests carry the digest and size; the signature covers the manifest payload, not the artifact directly.

D3 - Platform signing is delegated

  • macOS: [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.
  • Windows: [bundle.windows] maps to WindowsSettings (certificate thumbprint, digest algorithm, timestamp URL/TSP, custom sign command + args, downgrade policy). WebView2 remains skipped.
  • Auro does not shell out to codesign/signtool itself; the bundler owns the platform commands.

D4 - No signing secrets in the repository

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.

Interfaces

#![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

Acceptance

  1. Sign/verify accepts the exact bytes and rejects a changed byte or malformed signature (auro-sign tests).
  2. Key files round-trip and are 0600 on Unix (key_file_round_trips_with_owner_only_permissions).
  3. File signing/hashing works and rejects tampering (signs_and_verifies_a_file_and_hashes_it).
  4. [bundle.macos]/[bundle.windows] values reach the bundler settings (auro-bundle maps_signing_settings).
  5. auro generate-key writes a loadable key (auro-cli test).
  6. Unsigned Linux/Windows/macOS bundles still build; platform signing is not claimed without credentials.
  7. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Keychain/HSM-backed keysPlatform-services/keychain slice
Notarization credential wiring and CI secret setupSigning CI follow-up
Windows certificate provisioning and signtool verificationWindows signing follow-up
Key rotation and revocationUpdater/trust spec
Timestamp format for manifestsSpec 0012 / update service

0012 - Update manifests

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).

Scope

  • auro-update: manifest format v2, signing, verification, JSON encode/decode.
  • Artifact metadata: size and lowercase hex SHA-256.
  • Optional signed delta and rollout metadata (spec 0028).
  • auro manifest --artifact ... --key ... --out ... to produce a signed manifest.
  • Platform keys (<os>-<arch>) and publication timestamps as caller-supplied text.

Out of scope

  • Downloading, staging, applying or rolling back in this spec (the runtime is 0013 and 0014).
  • Delta application and rollout selection implementation details (spec 0028).
  • Channels, rollback execution, hosting behavior.
  • Hosting and CDN behavior.
  • Key distribution beyond the public key string; no built-in key pinning in this slice.
  • UI for update prompts.

Decisions

D1 - Format v2 is a flat JSON object with optional fields

{
  "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.

D2 - Signature covers a canonical payload

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.

D3 - Artifact metadata is verified separately

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.

D4 - CLI shape

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.

D5 - Trust, not installation

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.

Interfaces

#![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>;
}
}

Acceptance

  1. Signed manifest verifies; tampering with a field fails (signs_and_verifies_a_manifest, rejects_a_tampered_field).
  2. Empty signature, unknown format and malformed SHA-256 fail with the typed errors (rejects_an_empty_signature_and_unknown_format, rejects_a_malformed_artifact_hash).
  3. Artifact size/hash and manifest signature are both checked; a changed artifact fails (verifies_an_artifact_and_its_metadata).
  4. JSON round-trips byte-for-byte at the value level (json_round_trips).
  5. The CLI creates a manifest that verifies and describes the artifact (auro-cli release test).
  6. Delta/rollout metadata is signed and verified; see spec 0028.
  7. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Download/apply/staging/restart and rollbackUpdater runtime / AppImage / Windows and macOS / journal and restart
Deltas/patches and staged rollout percentagesBinary deltas and staged rollout
Key pinning and rotation inside the appTrust/update client spec
Update channels and UIPlatform/update UX follow-up
Hosting/CSP and mirror behaviorRelease service follow-up

0013 - Updater runtime: check, download and stage

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.

Scope

  • 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.
  • Content-addressed staging with safe extension preservation, atomic publication and reuse of a staged file that still verifies.

Out of scope

  • Installing, launching an installer, replacing the running app, restarting, and rollback (Linux AppImage apply/rollback is spec 0014; Windows/macOS apply is spec 0025; package-manager artifacts remain separate).
  • Channels and update UI.
  • Background scheduling, retry policy, resume of an interrupted download and UI prompts.
  • Key distribution, rotation and revocation inside the app.
  • Hosting and CDN behavior.

Decisions

D1 - Verify the offer before moving bytes

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:

DecisionMeaningdownload behavior
UpToDateoffered version equals the running versionrefuses
Availableoffered version is newerdownloads/stages
Downgradeoffered version is olderrefuses

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.

D2 - Staging is content-addressed

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.

D3 - Exact size, then hash, then atomic publish

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.

D4 - HTTP client and limits

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.

D5 - Deltas and rollout are separate signed fields

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.

D6 - Staging is not installation

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.

Interfaces

#![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.

Acceptance

  1. Newer, equal and older signed manifests return 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).
  2. A manifest with the wrong signature fails before any network request (verifies_before_touching_the_network).
  3. A local HTTP server serves the artifact; 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).
  4. A tampered body is rejected with ArtifactHash; a short body with ArtifactSize; an oversized body with ArtifactTooLarge; none leaves a final artifact (rejects_tampered_short_and_oversized_downloads).
  5. An equal version is refused before the network (refuses_to_stage_an_up_to_date_version).
  6. stage_from_path copies and verifies a local artifact (stages_a_local_artifact).
  7. Manifest::verify rejects a SHA-256 that is not 64 lowercase hexadecimal characters (rejects_a_malformed_artifact_hash).
  8. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Install/restart/rollback by platformAppImage apply / Windows and macOS apply / restart spec
Deltas and staged rollout selectionBinary deltas and staged rollout
Persistent update journal and resumeUpdate journal / resume spec
Key rotation/revocation and pinning in the appTrust/update client spec
Update channels, prompts and schedulingPlatform/update UX follow-up

0014 - AppImage apply and rollback

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.

Scope

  • 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.
  • Atomic in-place replacement, executable permissions, and a backup that survives a crash until explicitly discarded.

Out of scope

  • .deb/.rpm package installation, macOS .dmg/.pkg, and the Windows/MSI/NSIS and macOS .app details owned by spec 0025.
  • Restarting the app, waiting for a process to exit, or a helper-process protocol; the journal/ restart handoff is spec 0026.
  • Deltas, staged rollout, update channels and downgrade policy.
  • Preserving owner, group, extended attributes, SELinux labels or other file metadata beyond mode.
  • Signature verification; the artifact is already a StagedUpdate.

Decisions

D1 - AppImage is replaced as a single file

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.

D2 - A backup is created before the replacement

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.

D3 - Rollback is an atomic rename of the backup

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.

D4 - Apply is Linux-only, not a generic installer

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.

D5 - No automatic restart

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.

Interfaces

#![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.

Acceptance

  1. Installing replaces the target bytes, sets mode 0755, and retains the old bytes in the receipt's backup; rollback restores the old bytes and mode (installs_and_rolls_back_an_appimage).
  2. discard removes the backup and leaves the installed file (discards_the_backup_after_success).
  3. A missing target and a non-file target fail with typed errors (rejects_a_missing_or_non_file_target).
  4. A missing staged artifact fails without changing the target (missing_staged_artifact_leaves_the_target_untouched).
  5. A rollback with a missing backup reports RollbackBackupMissing and leaves the installed file (rollback_reports_a_missing_backup).
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Windows MSI/NSIS apply and privilege handlingWindows and macOS apply / Windows UX
macOS .dmg/.pkg replacement and notarizationmacOS updater spec
.deb/.rpm package-manager updatesLinux package apply
Restart/helper protocol and crash-safe receiptUpdate journal and restart helper
Preserving xattrs, SELinux labels and ownershipPlatform apply hardening
Rollout, deltas and downgrade policyUpdater rollout spec

0015 - Single instance

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.

Scope

  • auro-core::AppInstance: acquire an advisory per-user file lock and report primary/secondary.
  • InstanceMessage: forwarded arguments and working directory.
  • Primary listener and secondary forwarding over a local socket.
  • 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.
  • Lock/socket naming, owner-only lock permissions on Unix, and OS release on exit/crash.

Out of scope

  • Custom activation policy; App::activate_on_second_instance() focuses the first root by default, while apps with other needs use InstanceMessage and on_event.
  • Deep-link/file association policy; forwarded arguments are just arguments.
  • Cross-user or system-wide single-instance enforcement.
  • Cleaning up lock or socket files after exit (the lock file is retained; the socket file is reused or overwritten on the next start).
  • Defending against a same-user process that deliberately pre-creates or locks the file.
  • A stable public IPC protocol for third-party clients.

Decisions

D1 - Use the standard library's advisory file lock

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.

D2 - The lock lives in a per-user runtime directory

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.

D3 - Secondary startup forwards, then exits with an error

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".

D4 - Opt-in per app

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.

D5 - Guard and listener lifetime are the app lifetime

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.

D6 - Local socket, dual framing with an acknowledgement

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.

Interfaces

#![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();

Acceptance

  1. The first guard is primary; a second guard for the same name is secondary; after dropping the first, a new guard is primary again (first_guard_is_primary_and_second_is_not).
  2. A secondary forwards an InstanceMessage to the primary listener (forwards_a_message_to_the_primary_listener).
  3. Primary forwarding and secondary listening are rejected (primary_cannot_forward_or_secondary_cannot_listen).
  4. An empty identifier is a typed AuroError::Instance (empty_name_is_rejected).
  5. Lock-file names replace separators and cannot escape the lock directory (path_is_sanitised).
  6. App::single_instance() is opt-in and sets the builder flag; the activation helper enables both flags (single_instance_is_opt_in).
  7. AuroError::Instance reports kind "instance" and includes name/message (instance_errors_have_context_and_kind).
  8. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Custom activation behaviorApp policy / on_event
File and deep-link routing into the primaryDeep-link and instance IPC follow-up
Lock/socket cleanup policyOperations follow-up
Stable IPC protocol for third-party clientsRevisit only if required
Windows/macOS behavior under real desktop sessionsPlatform audit

0016 - Capability manifests and enforcement

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.

Scope

  • auro-perms: a Policy with deny-by-default grants for fs, net, shell, clipboard, notification and keychain.
  • Scoped capabilities (fs, net, shell) match a glob pattern against the value being acted on.
  • Typed Denied errors naming subject, capability and value.
  • auro::perms re-export for app and host code.

Out of scope

  • Sandboxing first-party app code. If the app author writes it, it runs.
  • OS-level sandboxing (App Sandbox, seccomp, AppContainer).
  • A manifest file format; the host constructs Policy in code today.
  • Per-window grants, plugin upgrade prompts and an allow-all mode.
  • Runtime I/O: the crate answers verdicts only; the effect site performs the effect.

Decisions

D1 - Deny by default

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.

D2 - Scoped capabilities carry a glob pattern

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.

D3 - Unscoped capabilities carry no pattern

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.

D4 - The denial names what failed

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.

D5 - No I/O in the crate

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.

Interfaces

#![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")?;

Acceptance

  1. Policy::deny_all() denies every check (denies_by_default).
  2. Unscoped capabilities are granted and denied independently of other subjects (allows_an_unscoped_capability, scopes_are_subject_scoped).
  3. Scoped grants match their glob and reject out-of-scope values, including subjects outside the grant (matches_a_scoped_grant, rejects_an_out_of_scope_value).
  4. Capability strings round-trip and an invalid pattern or scope mismatch is rejected (capability_strings_round_trip, rejects_an_invalid_pattern, rejects_a_scope_mismatch).
  5. A filesystem value that is relative or contains ./.., and a shell value containing ./.., are denied before glob matching (rejects_a_traversal_or_relative_filesystem_value).
  6. auro::perms re-exports the same API surface (crates/auro/src/lib.rs).
  7. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Manifest file format and load pathPlugin host spec
Per-window grants for the webview escape hatchWebview hatch spec
Plugin upgrade that widens scopesPlugin host spec
Systemd-style units for scoped shell/notificationsPlatform services spec

0017 - Autostart

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.

Scope

  • 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).
  • Platform modes: XDG autostart on Linux, Launch Agent on macOS, per-user registry entry on Windows.
  • auro::services::Autostart re-export.

Out of scope

  • System-wide autostart or admin elevation.
  • Editing existing autostart entries created by other tools.
  • Scheduling, delayed start, or start conditions beyond login.
  • Custom app bundle configuration on macOS.
  • Other platform services.

Decisions

D1 - Delegate macOS and Windows, own the Linux entry

Auro writes the Linux XDG entry itself and delegates the macOS Launch Agent and Windows registry entry to auto-launch. The platform modes are:

PlatformModeArtifact
LinuxXdgAutostart~/.config/autostart/<app>.desktop
macOSLaunchAgent~/Library/LaunchAgents/<app>.plist
WindowsCurrentUserHKCU\...\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.

D2 - Least privilege on Windows

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.

D3 - The current executable is a convenience, not a policy

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.

D4 - No admin, no silent fallback

The service does not fall back to a different mechanism when enable fails. A failed enable is an error the app can surface.

Interfaces

#![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()?;
}

Acceptance

  1. A freshly created service reports not enabled (reports_disabled_by_default).
  2. enable and disable round-trip the autostart state (enables_and_disables_the_service).
  3. The Linux entry honors XDG_CONFIG_HOME and quotes Exec paths/arguments with spaces (autostart_dir_honors_xdg_config_home, linux_entry_quotes_paths_and_arguments_with_spaces).
  4. A relative, missing or non-file app_path is rejected (rejects_a_relative_or_missing_app_path).
  5. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
System-wide autostart and admin elevationAutostart follow-up
Custom macOS bundle configurationAutostart follow-up
Scheduling and start conditionsAutostart follow-up
Other platform servicesPlatform services specs

0018 - Notifications

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.

Scope

  • 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.

Out of scope

  • Icons, images, actions, sounds, urgency or channel selection.
  • Scheduling or repeating notifications.
  • Notification handling after show (close, click, action callbacks).
  • Other platform services.

Decisions

D1 - notify-rust is the default backend

Auro 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.

D2 - The backend is pluggable for tests

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.

D3 - Show only

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.

Interfaces

#![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")?;

Acceptance

  1. show sends the title and body to the backend (sends_the_title_and_body_to_the_backend).
  2. A backend error surfaces as NotificationsError (backend_errors_surface).
  3. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  4. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Click/action callbacks and closing notificationsNotification UX spec
Icons, images, urgency and channelsNotification UX spec
Notification categories and quiet hoursNotification UX spec
Other platform servicesPlatform services specs

0019 - Keychain

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.

Scope

  • auro-services::Keychain: set, read and delete one secret.
  • CredentialStore: a pluggable store trait; the default is keyring.
  • auro::services::Keychain re-export.

Out of scope

  • Multiple entries per service/user.
  • Key rotation, expiry or secure in-memory handling.
  • Protecting secrets from the user who owns the machine.
  • Platform-specific options (biometric prompt, per-service access controls).
  • Other platform services.

Decisions

D1 - keyring is the default store

Auro 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.

D2 - One entry per service/user

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.

D3 - The store is pluggable for tests

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.

D4 - Errors surface as typed

KeychainError wraps the platform store error. The caller sees the failure immediately; there is no retry or fallback inside the service.

Interfaces

#![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()?;

Acceptance

  1. set_password and get_password round-trip, and delete_credential removes the secret (round_trips_a_secret).
  2. A store error surfaces as KeychainError (backend_errors_surface).
  3. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  4. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Multiple entries and service namespacesKeychain follow-up
Key rotation, expiry and secure memoryKeychain follow-up
Platform-specific access controlsKeychain follow-up
Other platform servicesPlatform services specs

0020 - Global shortcuts

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.

Scope

  • 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.

Out of scope

  • Registration persistence across app restarts.
  • Custom key parsing outside global-hotkey.
  • Callbacks for key release, repeat suppression or modifier-only hotkeys.
  • Other platform services.

Decisions

D1 - global-hotkey is the default backend

Auro 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.

D2 - The backend is pluggable for tests

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.

D3 - Pressed events dispatch on a service thread

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.

Interfaces

#![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")?;

Acceptance

  1. register and unregister call the backend with the hotkey (registers_and_unregisters_the_hotkey).
  2. A pressed hotkey invokes its callback (dispatches_a_pressed_hotkey).
  3. An invalid callback hotkey is rejected before the backend is called (rejects_an_invalid_callback_hotkey).
  4. A backend error surfaces as ShortcutsError (backend_errors_surface).
  5. An invalid hotkey is rejected before registration (rejects_an_invalid_hotkey).
  6. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  7. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Persisting shortcuts across restartsShortcut UX spec
Custom key parsingShortcut UX spec
Release events and repeat suppressionShortcut UX spec
Other platform servicesPlatform services specs

0021 - Tray

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.

Scope

  • 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.

Out of scope

  • App bundle icon discovery or packaging; apps provide RGBA pixels.
  • Tray persistence across app restarts.
  • PNG/theme file decoding.
  • Submenus, check items, icons-in-menu and accelerators.
  • Other platform services.

Decisions

D1 - tray-icon is the default backend

Auro 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.

D2 - The backend is pluggable for tests

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.

D3 - Menus, click callbacks and icons

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.

Interfaces

#![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)?;

Acceptance

  1. set_visible toggles the backend and is reflected by is_visible (shows_and_hides_the_icon).
  2. set_tooltip passes the tooltip to the backend and can clear it (updates_the_tooltip).
  3. A valid RGBA icon can be set and cleared; invalid pixels are rejected (sets_and_clears_the_icon).
  4. set_menu passes the items to the backend and menu events reach the callback (sets_a_menu_and_dispatches_its_events).
  5. Click events reach the callback (dispatches_clicks).
  6. A backend error surfaces as TrayError (backend_errors_surface).
  7. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  8. 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.

Open questions

QuestionWhere it settles
PNG/theme icon decodingTray UX spec
Tray persistence across restartsTray UX spec
Submenus, check items and acceleratorsTray UX spec
Other platform servicesPlatform services specs

0022 - Deep links

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.

Scope

  • 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.

Out of scope

  • macOS CFBundleURLTypes editing; the packager owns the bundle's Info.plist.
  • Linux .desktop installation by the packager; the service writes a user entry and calls xdg-mime.
  • Authentication, consent prompts and unknown-origin policy.
  • Universal links / HTTPS associations.

Decisions

D1 - A closed scheme list

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.

D2 - Registration is per user

register_scheme always acts in the current user's namespace:

PlatformMechanism
WindowsHKCU\Software\Classes\<scheme> via reg.exe
LinuxXDG desktop entry plus xdg-mime default
macOSpackager'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.

D3 - Queue until the app asks

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.

D4 - Parsing is defensive

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.

Interfaces

#![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`
}

Acceptance

  1. A valid scheme://host/path?key=value parses into scheme, host, segments and query (parses_a_deep_link).
  2. Unknown schemes and traversal paths are dropped (rejects_an_unknown_scheme, rejects_a_traversal_path).
  3. Empty or malformed schemes are rejected before registration (rejects_an_empty_or_bad_scheme).
  4. Cloned 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.
  5. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Universal links / HTTPS associationsDeep-link follow-up
macOS bundle registration automationPackager follow-up
Unknown-origin consent policyDeep-link UX spec

0023 - Keyboard activation

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.

Scope

  • auro_ui::Button is focusable and a tab stop.
  • Enter and Space with no modifiers invoke the same handler as a mouse click.
  • A held key does not repeat activation.
  • Headless test proving tab focus and keyboard activation.

Out of scope

  • AccessKit or any screen-reader tree. GPUI 0.2.2 does not expose one.
  • IME/composition behavior.
  • Focus-ring styling and tokens.
  • Full tab order across every primitive.
  • Shortcut/menu navigation outside the focused control.

Decisions

D1 - Tab focus is automatic

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.

D2 - Enter and Space share the click path

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.

D3 - Ignore modifiers and held keys

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.

Interfaces

#![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.

Acceptance

  1. A focused button activates on Enter and then Space, and the click count advances (button_activates_with_enter_and_space).
  2. Existing mouse activation still passes (clicking_button_dispatches_async_command_and_updates_view).
  3. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
AccessKit tree and screen-reader parityUpstream GPUI / accessibility spec
IME and composition behaviorPlatform input audit
Focus-ring styling and tokensDesign-system follow-up
Full tab order across primitivesAccessibility follow-up

0024 - Alpha release and crates.io

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.

Scope

  • One version for every crate: 0.1.0-alpha.1.
  • Publish the eleven workspace crates in dependency order.
  • Per-crate README, homepage, keywords/categories and licence files.
  • publish = ["crates-io"] only in the release commit.
  • Facade features: services are opt-in; tray is separately opt-in.
  • auro new emits a path dependency inside this checkout and a version dependency when the CLI is installed from crates.io.

Out of scope

  • Changing the public API after the alpha except for critical fixes.
  • AccessKit/IME; updater deltas/rollout now have their own spec 0028.
  • Signed/notarized release artifacts; those remain credential-gated.
  • A website, announcement, or support policy beyond the existing docs.

Decisions

D1 - Alpha version

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.

D2 - Publish leaves first

crates.io resolves dependencies from the registry, not from path dependencies. Publication order:

  1. auro-macros, auro-ipc, auro-sign, auro-perms, auro-services
  2. auro-core
  3. auro-update
  4. auro-ui
  5. auro-bundle
  6. auro
  7. auro-cli

The 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.

D3 - Services are opt-in at the facade

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.

D4 - Scaffold emits the right dependency

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.

D5 - Metadata is release material

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.

D6 - Publication is intentional

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.

Acceptance

  1. cargo metadata reports 0.1.0-alpha.1 for every crate and no path-only internal dependency lacking a registry version.
  2. cargo package -p <leaf> succeeds for each leaf crate, and cargo publish --dry-run -p <leaf> succeeds after the release switch.
  3. 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.
  4. cargo test -p auro-cli covers the in-repo path and installed-version scaffold modes.
  5. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.
  6. The release commit is tagged and all crates are published in the order above, with the rate-limit waits recorded.

Progress (2026-11-17)

  • Workspace version and all internal dependency requirements are 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.
  • Every crate has a crate-root README, homepage, keywords and categories; 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.
  • Release switch, tag and ordered upload completed; see the publication record below.

Publication (2026-11-18)

  • Tag v0.1.0-alpha.1 points at ac4d996 (the merge of the release-preparation changes).
  • All eleven crates report 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.
  • The crates.io listing is the publication evidence. The rate-limit waits were not retained as a repository log, so acceptance item 6 is satisfied for the tag and versions, not for a retained wait log.

Publication (2026-11-19) - 0.1.0-alpha.2

  • Workspace version and internal requirements are 0.1.0-alpha.2; all eleven crates report it as their maximum published version on crates.io.
  • The release carries the StatusNotifierItem tray backend (no GTK), the typed Wayland startup failure (AuroError::Platform) and the Windows journal ancestor validation.
  • Tag v0.1.0-alpha.2 points at the release commit.

Publication (2026-11-20) - 0.1.0-alpha.3

  • Workspace version and internal requirements are 0.1.0-alpha.3; all eleven crates report it as their maximum published version on crates.io.
  • The release carries the twenty fixes from #28-#47 and the same-app Tauri/Electron benchmark harness.
  • Tag v0.1.0-alpha.3 points at the release commit.

Publication (2026-11-20) - 0.1.0-alpha.4

  • Workspace version and internal requirements are 0.1.0-alpha.4; all eleven crates report it as their maximum published version on crates.io.
  • The release carries the eight follow-up fixes from #49-#56.
  • Tag v0.1.0-alpha.4 points at the release commit.

Publication (2026-11-21) - 0.1.0-alpha.5

  • Workspace version and internal requirements are 0.1.0-alpha.5; all eleven crates report it as their maximum published version on crates.io.
  • The release carries the five follow-up fixes from #58-#62.
  • Tag v0.1.0-alpha.5 points at the release commit.

Publication (2026-11-21) - 0.1.0-alpha.6

  • Workspace version and internal requirements are 0.1.0-alpha.6; all eleven crates report it as their maximum published version on crates.io.
  • The release carries the two follow-up fixes from #64-#65.
  • Tag v0.1.0-alpha.6 points at the release commit.

Publication (2026-11-21) - 0.1.0-alpha.7

  • Workspace version and internal requirements are 0.1.0-alpha.7; all eleven crates report it as their maximum published version on crates.io.
  • The release carries the two follow-up fixes from #67-#68.
  • Tag v0.1.0-alpha.7 points at the release commit.

Open questions

QuestionWhere it settles
Final README copy and screenshotsRelease follow-up
Whether auro-perms is also feature-gatedAlpha follow-up
Whether auro keeps a default service featureAlpha follow-up
Long-term release automation/trusted publishingRelease engineering follow-up

0025 - Windows and macOS apply

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.

Scope

  • 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.
  • Facade re-exports behind the updater feature, gated by the host OS.

Out of scope

  • Elevation, UAC, sudo, admin prompts or a privileged helper process.
  • Waiting for the running app to exit, relaunching it, or a restart protocol; the journal/restart handoff is spec 0026.
  • Windows rollback. The MSI/NSIS installer owns its install transaction.
  • macOS .dmg mounting, notarization and Apple package-signature policy; .pkg apply is spec 0031.
  • .deb/.rpm package-manager apply.
  • Preserving extended attributes, ACLs, SELinux labels or ownership beyond what the archive and filesystem copy provide.
  • Deltas, staged rollout, update channels and downgrade policy.

Decisions

D1 - Windows runs the OS installer, never a shell

WindowsInstaller inspects the staged artifact extension:

FormatProgramArguments
.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.

D2 - macOS swaps the .app directory from a zip

MacAppInstaller 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.

D3 - The command runner is the test seam

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.

D4 - The installer does not restart or elevate

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.

Interfaces

#![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.

Acceptance

  1. MSI runs msiexec with /i, the staged path, /qn and /norestart (runs_msi_installer_silently).
  2. NSIS runs the staged .exe with /S (runs_nsis_installer_silently).
  3. 3010/1641 report restart_required; another code is InstallerFailed and keeps the code (maps_reboot_required_and_failure).
  4. An unknown Windows artifact is UnsupportedInstaller (rejects_unknown_artifacts).
  5. A .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).
  6. discard removes the backup (discards_the_backup_after_success).
  7. An archive with no .app fails with AppBundleMissing and leaves the target unchanged (rejects_an_archive_without_an_app_bundle).
  8. A .dmg staged artifact is rejected as unsupported (rejects_an_unsupported_archive).
  9. A symlink in the extracted bundle that resolves outside the extraction tree is rejected as UnsafeArchive (rejects_symlinks_escaping_the_bundle), while an in-bundle symlink is allowed (allows_symlinks_inside_the_bundle).
  10. A zip with two top-level .app bundles is rejected without touching the target (rejects_an_ambiguous_archive).
  11. Missing/non-directory macOS targets fail with 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).
  12. A missing staged artifact is 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).
  13. 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.

Open questions

QuestionWhere it settles
Windows elevation, reboot and installer UI policyWindows update UX/spec
macOS .dmg applymacOS disk-image apply spec
macOS .pkg applymacOS package apply
.deb/.rpm package-manager applyLinux package apply, elevation
Restart/helper protocol and crash-safe apply journalUpdate journal and restart helper
macOS code-signing preservation and notarization checksmacOS notarization
Automatic downgrade policyLinux package rollback

0026 - Update journal and restart helper

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.

Scope

  • auro-update::ApplyJournal: a durable, atomically written JSON record for one apply attempt.
  • ApplyKind: None, AppImage, WindowsInstaller, MacApp, MacPkg, DebPackage, RpmPackage.
  • States: Prepared, Applied, RebootRequired, Failed, RolledBack, Restarted.
  • Helper-side platform apply for a prepared journal, using the installers from specs 0014/0025.
  • An optional caller-supplied older .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.
  • Facade re-exports behind the updater feature.

Out of scope

  • .dmg, .deb/.rpm automatic rollback and signed macOS helper policy; .pkg apply is spec 0031.
  • Root-owned helper installation, UAC, sudo or Auro-managed passwords.
  • A separate helper binary, service, launchd job or Windows scheduled task.
  • State snapshots across the restart; that contract belongs to spec 0004.
  • Automatic cleanup of journals, backups or old artifacts.
  • Automatically wiring reconcile/finalize into every app startup; the app calls them.
  • Timeouts longer than the fixed helper wait, or a user-facing progress UI.

Decisions

D1 - The journal is the durable source of truth

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.

D2 - The helper is the same executable, not a second binary

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.

D3 - The helper applies a prepared plan, then relaunches

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.

D4 - The helper removes its own trigger and detaches

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.

D5 - The journal's directory is a trust boundary

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).

Interfaces

#![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.

Acceptance

  1. A prepared journal round-trips through disk; state, version, target, backup and relaunch command survive (round_trips_state_through_disk).
  2. Missing and unsupported-format journals are typed errors (rejects_a_missing_or_unknown_journal).
  3. 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).
  4. 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).
  5. The helper refuses an unapplied journal and a state flipped while waiting (helper_rejects_an_unapplied_journal, helper_refuses_a_state_flipped_while_waiting).
  6. 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).
  7. A rollback plan survives the journal round trip and is rejected for a non-package apply (round_trips_a_package_rollback_plan, rejects_a_rollback_plan_for_a_non_package_apply).
  8. A missing relaunch executable is rejected and recorded (helper_records_a_launch_failure).
  9. A missing, malformed, old-format or non-sibling-lock journal is typed (rejects_a_missing_or_unknown_journal, rejects_malformed_json, reports_an_old_format_before_schema_fields, rejects_a_non_sibling_lock_path).
  10. App::try_run enters helper mode from RESTART_HELPER_ENV before config/GPUI (compile-time façade check).
  11. 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.

Open questions

QuestionWhere it settles
Automatic startup recovery and cleanup policyApply/restart follow-up
Root-owned helper, polkit policy and an OS service/scheduled taskPackage elevation
Automatic package rollbackPackage rollback
Journal/backup cleanup policyOperations follow-up
Persistent download resumeUpdater resume spec
State preservation across the relaunchSpec 0004 snapshot contract

0027 - Linux package apply

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.

Scope

  • auro-update::LinuxPackageInstaller: detect .deb/.rpm, run the package manager and classify its exit code.
  • ApplyKind::DebPackage/ApplyKind::RpmPackage for helper-side apply.
  • Facade exports on Linux.

Out of scope

  • A root-owned helper, sudo, polkit policy installation or an Auro-managed password prompt.
  • Choosing or retaining the package to downgrade to; the caller supplies it (spec 0030).
  • Signature verification of the package itself; the staged artifact is already verified by the unsigned manifest hash.
  • Choosing between dpkg, apt, rpm, dnf or zypper; this uses the low-level package tool.
  • Package-manager UI, progress reporting, restart scheduling and dependency repair.

Decisions

D1 - Absolute package-manager paths, shell-free

The staged extension selects the command:

FormatProgramArguments
.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.

D2 - Elevation is a separate, explicit policy

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.

D3 - The helper reuses the platform apply layer

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.

Interfaces

#![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.

Acceptance

  1. .deb runs /usr/bin/dpkg -i <staged> (runs_dpkg_for_a_deb).
  2. .rpm runs /usr/bin/rpm -U <staged> (runs_rpm_for_an_rpm).
  3. A non-zero package-manager code is InstallerFailed (reports_package_manager_failure). Elevated failures are ElevationFailed (reports_pkexec_authorization_failure).
  4. An unknown extension is UnsupportedInstaller (rejects_unknown_artifacts).
  5. ApplyKind::DebPackage/RpmPackage dispatch through the elevated helper on Linux.
  6. 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.

Open questions

QuestionWhere it settles
Root-owned helper and narrowed polkit policyPackage elevation
Automatic package rollback and downgrade policyPackage rollback
apt/dnf/zypper policy and dependency repairPackage-manager spec
Package signature verificationRelease/package trust spec
Restart scheduling after package installApply/restart follow-up

0028 - Binary deltas and staged rollout

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.

Scope

  • Manifest format v2 with optional 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.
  • CLI auro delta and the matching auro manifest delta/rollout options.

Out of scope

  • A server-side rollout control plane or percentage update without a new manifest.
  • Delta chains, reverse deltas or delta rollback.
  • Automatic full-download fallback inside download_delta; the caller can fall back to download.
  • Delta patches for directory/bundle artifacts. The patch applies to the full staged file.
  • Signed separate delta files; the patch hash is covered by the signed manifest.
  • Key rotation, channels and rollout telemetry.

Decisions

D1 - Manifest v2 adds optional signed fields

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.

D2 - Delta is bsdiff-compatible and base-bound

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:

  1. require an available (and selected) manifest;
  2. compare the running version and base hash;
  3. verify the patch size and SHA-256;
  4. apply it to the base;
  5. verify the resulting full artifact size and SHA-256 against the manifest; and
  6. persist the full artifact at the same content-addressed path as a full download.

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.

D3 - Rollout is deterministic and fails closed

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.

D4 - Full downloads remain the fallback

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.

Interfaces

#![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).

Acceptance

  1. Manifest v2 signs/verifies delta and rollout fields and rejects a rollout above 100 (signs_delta_and_rollout_metadata, rejects_an_invalid_rollout_percentage).
  2. A local delta patch is applied to its matching base; the full artifact verifies (applies_a_local_delta_and_verifies_the_full_artifact).
  3. A delta for a different base is rejected (rejects_a_delta_for_the_wrong_base).
  4. 0% is HeldBack, 100% is Available, a partial rollout without a key is held, and a key selects deterministically (staged_rollout_is_deterministic_and_gates_downloads).
  5. CLI writes a delta patch and manifest delta/rollout metadata (creates_a_patch_file, writes_delta_metadata_and_rollout).
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Server-side percentage control without a new manifestRollout service follow-up
Delta chains and reverse deltasDelta follow-up
Delta telemetry and bandwidth accountingRelease metrics follow-up
Channel policy and forced 100% completionRelease UX/spec

0029 - Linux package elevation

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.

Scope

  • LinuxElevation: None (direct) or Pkexec (polkit).
  • LinuxPackageInstaller::elevated() and with_elevation.
  • Helper-side package apply through pkexec /usr/bin/dpkg -i ... or pkexec /usr/bin/rpm -U ....
  • Passing the opened staged artifact through the helper's /proc/<pid>/fd/<fd>.
  • Typed UpdateError::ElevationFailed for a non-zero pkexec result.

Out of scope

  • A root-owned helper binary, setuid installation, or a system polkit policy file.
  • sudo, password prompts implemented by Auro, or interactive terminal policy.
  • Package rollback, downgrade, dependency repair, or a package-manager preference policy.
  • Package signature verification independent of the signed manifest hash.
  • Progress UI, polkit agent installation, or headless/SSH authentication.

Decisions

D1 - Elevation is explicit and helper-side

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.

D2 - pkexec gets an argument vector, not a command string

The 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.

D3 - Failure is explicit; the package manager owns the transaction

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.

D4 - Polkit policy remains the deployment boundary

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.

Interfaces

#![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> }.

Acceptance

  1. Direct .deb still runs /usr/bin/dpkg -i <staged> (runs_dpkg_for_a_deb).
  2. Elevated .deb runs pkexec with /usr/bin/dpkg, -i, and a /proc/<pid>/fd/<fd> path (elevated_deb_runs_pkexec_dpkg_with_a_held_descriptor).
  3. Elevated .rpm runs pkexec with /usr/bin/rpm -U (elevated_rpm_runs_pkexec_rpm).
  4. A pkexec exit of 126 is ElevationFailed (reports_pkexec_authorization_failure).
  5. A package-manager exit of 1 through pkexec is InstallerFailed (elevated_package_manager_failure_is_an_installer_failure).
  6. The restart helper routes ApplyKind::DebPackage/RpmPackage through the elevated installer.
  7. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Root-owned helper and a branded polkit policyPackaging/distro follow-up
Package rollback and downgrade policyPackage rollback
apt/dnf/zypper policy and dependency repairPackage-manager spec
Headless/SSH authorizationOperations follow-up

0030 - Linux package rollback

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.

Scope

  • 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.
  • Helper-side rollback when a .deb/.rpm apply fails with InstallerFailed.
  • dpkg --force-downgrade -i for a .deb.
  • rpm -U --oldpackage for an .rpm.
  • Reuse of LinuxElevation::Pkexec and the held-descriptor command path.
  • Typed InstallerFailed/ElevationFailed on failure.

Out of scope

  • Automatic rollback without a caller-supplied older package.
  • Downloading, discovering, repacking or retaining the previous package.
  • Deciding whether a downgrade is safe for dependencies or the system.
  • Package holds, pinning, channels and downgrade approval policy.

Decisions

D1 - The caller supplies the older package

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.

D2 - Use the package manager's explicit downgrade flag

FormatProgramArguments
.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.

D3 - Elevation and failure semantics are unchanged

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.

D4 - Automatic rollback is opt-in and only follows a package-manager failure

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:

  1. re-verifies the older manifest, artifact size/SHA-256 and host platform;
  2. requires the older manifest version to be strictly lower than the journal version;
  3. runs the elevated rollback path (dpkg --force-downgrade/rpm -U --oldpackage);
  4. marks the journal 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).

Interfaces

#![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(),
));

Acceptance

  1. .rpm rollback runs /usr/bin/rpm -U --oldpackage <staged> (rollback_rpm_uses_oldpackage).
  2. .deb rollback runs /usr/bin/dpkg --force-downgrade -i <staged> (rollback_deb_forces_a_downgrade).
  3. Elevated rollback passes the held /proc/<pid>/fd/<fd> path through pkexec (elevated_rollback_uses_the_held_descriptor).
  4. A package-manager failure is InstallerFailed with the exit code (rollback_reports_package_manager_failure).
  5. A missing staged artifact or unknown extension follows the install contract (StagedArtifactMissing/UnsupportedInstaller).
  6. 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).
  7. 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).
  8. A journal round-trips the rollback artifact and rejects a rollback plan for a non-package apply (round_trips_a_package_rollback_plan, rejects_a_rollback_plan_for_a_non_package_apply).
  9. Helper rollback verification refuses a same/newer version, a wrong platform and a tampered artifact (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).
  10. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Automatic rollback with a package obtained by AuroPackage transaction policy; Auro cannot obtain a previous package
Automatic rollback of AppImage/MSI/.app appliesPlatform installer receipts (specs 0014/0025)
Retaining or downloading the previous packageRelease artifact retention
Dependency-safe downgrade and holdsPackage-manager policy
Journal-driven rollback executionApply journal follow-up

0031 - macOS package apply

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.

Scope

  • MacPkgInstaller: detect .pkg, run /usr/sbin/installer -pkg <staged> -target /.
  • MacPkgElevation::{None, Osascript}.
  • ApplyKind::MacPkg for helper-side apply.
  • Facade exports on macOS.

Out of scope

  • .dmg mounting and copying.
  • Code-signing, notarization or Gatekeeper policy; the package is already the signed release artifact and the manifest hash is verified before apply.
  • A root-owned LaunchDaemon/helper, sudo, or a custom Authorization Services prompt.
  • Automatic rollback, downgrade, package receipts or uninstall policy.
  • Per-user installs, custom targets, MDM/configuration profiles and installer UI.
  • Verifying Apple package signatures independently of the signed manifest hash.

Decisions

D1 - Run the system installer shell-free

ModeProgramArguments
Direct/usr/sbin/installer-pkg <staged> -target /
Elevated/usr/bin/osascriptfixed 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.

D2 - Elevation is an explicit AppleScript prompt

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.

D3 - Failure is explicit and never relaunches

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.

Interfaces

#![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.

Acceptance

  1. Direct .pkg runs /usr/sbin/installer -pkg <staged> -target / (runs_the_macos_installer_for_a_pkg).
  2. Elevated .pkg runs osascript with the fixed quoted form script and the path as its argument (elevated_pkg_uses_osascript_and_quoted_form).
  3. A direct installer failure is InstallerFailed (reports_pkg_installer_failure).
  4. A prompt/authorization failure is ElevationFailed (reports_osascript_authorization_failure).
  5. An explicit None elevation policy runs the direct installer (explicit_none_elevation_runs_the_direct_installer).
  6. A non-.pkg artifact is UnsupportedInstaller (rejects_unknown_artifacts).
  7. ApplyKind::MacPkg dispatches through the elevated installer on macOS.
  8. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
macOS runtime verification and signed-package policymacOS release CI/spec
Notarization and Gatekeeper assessmentmacOS notarization
Root-owned privileged helper and artifact-copy ownershipmacOS hardening follow-up
Automatic rollback/uninstall policyPackage transaction policy

0032 - macOS notarization submission

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.

Scope

  • 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.

Out of scope

  • Codesigning; the artifact must already be signed with a Developer ID identity.
  • Creating or storing the keychain profile, Apple ID/API-key handling or secrets in config.
  • Gatekeeper assessment on a target Mac as proof of end-user acceptance; spctl --assess is a local check, not a formal notarization result.
  • Stapling a remote copy, or notarization of an unsigned .app.
  • Rebuilding or reordering the bundler's DMG after the .app ticket is stapled.
  • Windows Authenticode and Linux package signatures.
  • A notarization service account, CI secret policy or release-channel policy.

Decisions

D1 - notarytool is invoked shell-free with an absolute xcrun

MacNotarizer 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.

D2 - Submission, stapling and validation are separate, explicit steps

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.

D3 - Notarization is release hardening, not update trust

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.

D4 - auro bundle integration is opt-in and post-hoc

Setting [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.

Interfaces

#![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.

Acceptance

  1. Submission, stapling and validation use the exact xcrun argument vectors (submits_staples_and_validates_with_xcrun).
  2. --skip-staple/skip_staple=true runs only submission (can_skip_stapling).
  3. A failed submission does not run stapling (reports_submission_failure_and_does_not_staple).
  4. A failed staple or validation is reported (reports_stapling_failure_and_does_not_validate, reports_stapler_validation_failure).
  5. A .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).
  6. A bare zip requires --skip-staple (a_zip_needs_skip_staple_and_then_submits_only).
  7. 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).
  8. notarize_artifacts processes .app before .dmg and ignores non-macOS formats (notarizes_and_verifies_macos_artifacts_and_skips_other_formats).
  9. Missing artifacts, empty profiles and unsupported extensions fail before running a command (rejects_a_missing_artifact_empty_profile_or_unknown_extension).
  10. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
CI keychain profile and Apple credential policyRelease CI follow-up
Real notarytool submission and Gatekeeper acceptance on a MacmacOS release verification/credentials
DMG ordering with a stapled .appmacOS packaging follow-up
Automatic notarization for a .pkg built outside tauri-bundlermacOS packaging follow-up

0033 - Update journal trust boundary

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.

Scope

  • ApplyJournal path validation before a journal is read, written or used to spawn/await the helper.
  • The journal file, its parent directory, its ancestors (Unix and Windows) and the sibling lock file.
  • Unix ownership/mode/symlink checks and Windows reparse/owner/DACL checks.
  • A typed failure for an untrusted path, tested on Unix and on Windows CI.

Out of scope

  • Authenticity of the journal's contents beyond path trust. A journal in a trusted directory is written by the current user; that user can already run code as themselves.
  • Root/Administrator compromise, a compromised same-user session, kernel attacks or physical access.
  • A general effective-access model for Windows beyond the DACL walk, and a general TOCTOU-proof installer handoff.
  • Freshness, downgrade, replay, freeze, key rotation, revocation and mirror policy. Those are metadata properties, modelled in RFC 0001.
  • A new journal format or a migration to TUF metadata.

Decisions

D1 - The journal path is checked fail-closed, on the opened object

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.

D3 - Windows: reparse points, owner, DACL and ancestors

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.

D4 - Remaining limits are stated, not papered over

  • A local Administrator/root or the same user can replace the files; the threat model is another local user, not privilege escalation.
  • Windows ACL semantics are broader than the subset above: callback/object ACEs, central access policies and inherited ACEs that name a group are refused when they carry a dangerous right. That is deliberate fail-closed behaviour.
  • Windows ancestor validation is DACL-based, not a general effective-access check. It walks opened ancestors and treats an inherit-only ACE on an ancestor as applying to its children; the child is checked as the walk descends. The app must still use a per-user data directory.
  • The helper verifies the artifact before applying it, but a writeable staging directory still leaves a verify-then-open window. Moving the verified bytes through a held descriptor and asking the installer to consume that descriptor is platform-specific and remains open.
  • The journal may point at a staged artifact or relaunch executable outside the journal directory. Those paths are user-chosen and are not re-homed; the journal's directory is the trust anchor, not a sandbox for every path it names.

Interfaces

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.

Acceptance

Unix tests in crates/auro-update/src/journal.rs:

  • accepts_a_private_journal_directory_and_file
  • rejects_a_world_writable_journal_directory
  • rejects_a_world_writable_journal_file
  • rejects_a_symlinked_journal
  • rejects_a_shared_ancestor_directory
  • refuses_a_symlinked_lock_file
  • accepts_a_journal_in_a_private_symlinked_directory
  • refuses_to_create_a_journal_in_a_shared_directory

The 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.

Open questions

QuestionWhere it settles
Windows effective-access model beyond the DACL walkFollow-up; the current walk is deliberately fail-closed
Windows symlink privilege coverage on runners without developer modeCI follow-up; the test skips rather than failing
Staging-directory and installer-handoff TOCTOURFC 0001
Metadata expiry, generation, key rotation, revocation and mirror policyRFC 0001

Platform support

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.

Target matrix (1.0)

TierPlatformMinimumTargets
1macOS12 (Monterey)aarch64-apple-darwin, x86_64-apple-darwin
1LinuxUbuntu 22.04X11 and Wayland, x86_64-unknown-linux-gnu
1Windows10x86_64-pc-windows-msvc

Tier 1 means: builds in CI, tests run, a maintainer uses it, regressions are release blockers.

Current status

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.

PlatformBuildsTestsManually usedNotes
macOSCI clippy greenCI 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 greenubuntu-latest fmt, clippy and tests green-No desktop-session verification
Linux (Wayland)unverified in CIunverified in CIlocal only (niri)Phase 0/1 demos, hot-reload measurements and auro bench were run locally on niri/Wayland; no CI compositor job
WindowsCI clippy greenCI 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.

Security-relevant verification gaps

  • The single-instance private-directory, ownership and mode checks are unit-tested on Unix; no multi-user Linux or macOS desktop session has exercised them. Windows uses a machine-global named pipe and relies on its ACL; that isolation is unverified.
  • Updater signature, size and SHA-256 paths are unit-tested on every OS; TUF-style key rotation, revocation and a real signed release have not been exercised. Update artifacts are hashed in bounded chunks, but platform installers are only integration-tested where the host tools exist.
  • The macOS .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.

Linux system dependencies

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.

Honesty rule

The roadmap names immature Windows/Linux support as the biggest schedule risk and commits to publishing the support matrix from Phase 0. Therefore:

  • an unverified platform is listed as unverified, not as supported;
  • a platform that fails CI is removed from Tier 1 in the same change that breaks it;
  • "it compiles" is not "it works" - text input, IME, clipboard and window management are separate verification lines.

Performance budget

These numbers are the product argument. A framework that claims native performance and then ships a 40 MB binary has no reason to exist.

MetricTarget at 1.0Status
Cold start< 80 msLocal 5-run median 154.9 ms (first-frame request, not painted frame)
Idle RAM (hello world)< 40 MBLocal 5-run median 105.3 MB
Hello-world binary (stripped)< 6 MBLocal 15.6 MB
Edit to see (boundary data only)< 500 msMet 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 time16.6 ms at 60 fpsInherited from GPUI, unverified

How each metric is defined

Precision matters more than the number, because a budget you cannot reproduce is a slogan.

  • Cold start - process spawn to first painted frame, measured as the median of N runs on an idle machine, with the app installed as a bundled binary rather than run from target/debug.
  • Idle RAM - resident set size after first paint and 5 seconds of no input, hello-world app.
  • Binary size - release build, strip = "symbols", panic = "abort", .app/MSI/AppImage payload, not the directory total.
  • Edit to see - save event in the editor to a changed pixel, median of N edits, hot reload enabled, state preserved.

Process harness

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.

Enforcement

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:

  • benchmarks run on a pinned runner class, and the runner is recorded with the result;
  • results are committed as a baseline file, so a pull request shows a delta;
  • a regression beyond a stated tolerance fails the job, with an explicit 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.

Comparison runs

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:

TargetStartup medianp95Idle RSSIdle PSSPayload
Auro (GPUI)189.5 ms205.3 ms105.9 MB98.6 MB14.9 MB
Tauri 2.12.7 (WebKitGTK 2.54.2)417.4 ms507.6 ms500.7 MB314.5 MB6.7 MB
Electron 45.4.1420.5 ms451.9 ms589.2 MB291.1 MB273.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.

GPUI 0.3 spike (2026-11-18)

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?

Environment

  • CachyOS Linux 7.3.4-1, x86_64, 12 CPUs, 22 GiB RAM.
  • niri/Wayland (WAYLAND_DISPLAY=wayland-1, DISPLAY=:0).
  • rustc/cargo 1.99.1, dx 0.7.10.
  • New dependency set: 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.
  • The xattr 0.2.3 vendor patch is unused by this dependency graph; xattr 1.7.0 is in the tree.

Results

TargetCommandResult
auro-uicargo check -p auro-uipass after 34.8 s of dependency build
workspacecargo check --workspacepass after 2 API edits
examples/hellocargo checkpass
examples/log-viewercargo check with gpui-component =0.10.0pass without source changes
generated appauro new + cargo check --features hot-reloadpass after replacing gpui::Timer
hot reloadauro dev, [dev] hot = truepass; 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).

Broken APIs

Only two workspace call sites needed changes; the generated template needed one more.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. The spike hardcodes 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.

Hot reload

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):

Nmedianminmaxpatch-to-render
20296 ms285 ms415 ms0-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.

Platforms and accessibility

  • Only Linux x86_64 was built and run. 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.
  • Windows hot reload of element-returning view code was already blocked on 0.2.2 (main-thread stack overflow); this spike did not retest it. The data-boundary design remains the portable shape.
  • 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 is a dependency (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.

Recommendation

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:

  1. Pin 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.
  2. Move platform selection into auro-ui (the only crate that names GPUI) and add a per-target CI check for the platform crates.
  3. Change 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.
  4. Replace gpui::Timer in the template with smol::Timer (or a deliberate auro-ui re-export) and add smol to the generated ui crate.
  5. Re-run the hot-reload boundary benchmark and the examples/hello/log-viewer runtime, then decide whether to keep auro::hot or evaluate gpui-pre's own hot-reload feature.
  6. Drop the unused xattr patch only after the dependency graph proves it is unnecessary.

Evidence

  • Spike worktree: /run/media/pdl/data/Projetos/auro-wt-gpui03 (branch agent/gpui-0.3-spike).
  • Build logs: gpui03-check.log, gpui03-workspace.log in that worktree.
  • Hot-reload log: /tmp/auro-gpui03-dev.log; generated app: /tmp/auro-gpui03-demo.
  • The layout experiment is a throwaway app; it is not a committed example.
  • The spike branch is Linux-only and is not intended to merge. This page is the deliverable.

Repository standards

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.

Baseline files

PathEnforces
README.mdEnglish entry point: what it is, status, how to get involved
README.pt-BR.mdPortuguese mirror of README.md
ROADMAP.mdthe only place phases, dates and targets are defined
CONTRIBUTING.mdhow to build, test and submit
SECURITY.mdhow to report a vulnerability privately
CODE_OF_CONDUCT.mdContributor Covenant 2.1
CHANGELOG.mduser-visible changes, Keep a Changelog + SemVer
LICENSE-MIT, LICENSE-APACHEdual licence, see ADR 0006
.editorconfigLF endings, UTF-8, 2-space YAML/TOML, 4-space Rust
AGENTS.mdinstructions for AI coding assistants
rfcs/proposals that need discussion before a decision
docs/the published book (mdBook)
.github/workflows/ci.ymlformat, lint, test, docs build
.github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.mdthe 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.

Language

  • English is the source of truth for the README, the book, issues, pull requests, commit messages and code comments.
  • 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.
  • Do not translate identifiers, crate names, commands or error messages.
  • Portuguese is fine in Discussions, issues and reviews; the artefact that lands in the tree is English.

Commits and pull requests

  • Conventional Commits. 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.
  • Signed-off-by required (git commit -s), DCO 1.1. There is no CLA.
  • Squash merge. The pull request title becomes the commit subject, so it must satisfy the rule above.
  • One concern per pull request. Formatting churn, refactor and behaviour change do not share a diff.

Versioning and changelog

  • SemVer. Before 1.0, a breaking change bumps the minor version; the patch version is for compatible fixes. From 1.0, standard SemVer applies and the roadmap's API freeze takes effect.
  • 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.
  • Crates are published together at the same version; a workspace-local version skew is a bug.

Documentation

  • The book builds with mdBook from 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.
  • New chapters are one idea, linked from SUMMARY.md, and written in the same voice as the rest: direct, present tense, no marketing adjectives, no emoji.
  • API examples that cannot compile yet are fenced rust,ignore and carry a one-line note saying the API does not exist.
  • ADR vs RFC. A decision that has been made goes to docs/src/decisions/ and is immutable. A proposal that needs discussion goes to rfcs/ and is numbered. An accepted RFC produces an ADR.

Rust conventions

  • 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.

CI

Gates and supporting jobs, all required to be green before merge:

  1. cargo fmt --all --check (Linux leg)
  2. cargo clippy --workspace --all-targets --locked -- -D warnings (Linux, macOS, Windows)
  3. cargo test --workspace --locked (Linux, macOS, Windows)
  4. cargo build --workspace --locked on ubuntu-22.04 (published Linux floor)
  5. mdbook build docs
  6. workflow lint (actionlint)

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.