open-standards/wai/wai-quantum-desktop/README.md

Quantum Studio for the desktop

Quantum Studio as an app. The interface is the browser's. The engine underneath is the quantum job service's engine (wai_quantum::engine), built natively: it uses every core, holds as much memory as the machine has, and works offline.

• Each job runs in a process of its own, this binary run as worker, so a large job cannot take the app's memory with it, and Cancel ends it.
• The worker plans and runs; the app seals. It signs the answer with this user's key, the command line's (~/.config/wai/quantum-key), which never leaves the app.
• Step through and editing by the drawing run natively here: the debugger steps a program and lists its branches off the window's thread, and a drawing's edits, its SVG and LaTeX, and its description in words answer at once.
• Saved jobs, programs and drawings go to ~/Documents/Quantum Studio/. wai-quantum verify checks a saved job.
• The job service is one switch away, as in the browser.
• Your own hardware: the providers you listed with wai-quantum providers add are under Your hardware. A run asks the provider for its estimate first and shows a dialog before one that is not free; the app reads the credential from the keychain and seals the counts with your key, and the page never sees the credential.
• Memory: a job may take $WAI_QUANTUM_MEMORY_GB (16 by default). The plan says when a job needs more.
• Updates: a copy installed by its own installer looks for a newer version as it opens and offers it above the Studio. Nothing installs until you say so, and an update installs only when its signature verifies with the key the app carries, for the version announced; the app then restarts into it. Installers and updates says which copies update themselves.

What is stable

The app is an application. What it promises is the engine's, through what it saves: a job is the engine's job JSON, which follows its schemas, and its receipt verifies with wai-quantum verify in every later version. What each WAI Quantum version promises, and how a change is announced: the policy; what is deprecated: the deprecations.

Building

The app embeds the Studio's build, so build the Studio first:

(cd ../quantum-studio && npm ci && node build.mjs)
cargo build --locked --release             # add --features metal for the GPU state vector on macOS
./target/release/wai-quantum-desktop       # the app
./target/release/wai-quantum-desktop check # a job through the worker, sealed and verified, with no window

It draws with the operating system's own web view, so the app carries no browser of its own.

Installers and updates

A tag wai-quantum-desktop-v<version> (the version Cargo.toml and tauri.conf.json both state) runs the release workflow, which builds the installers on each platform and attaches them to the forge release of that tag, each with its SHA-256:

Platform	Assets (wai-quantum-desktop-<version>-<target>…)	Updates itself
macOS, Apple silicon and Intel (with the GPU state vector)	.dmg	yes, from Applications
Linux, x86_64 and arm64	.AppImage, .deb, .rpm	yes (the packages through the system's password prompt)
Windows, x86_64	-setup.exe	yes
Windows, x86_64	.zip, a portable copy, for package managers	no: the package manager updates it

The same run writes a Homebrew cask, a Scoop manifest and the update manifest (latest.json) from the assets it attached (release/manifests.py, from the templates beside it), and attaches them to the release. The tap and the bucket take the cask and the manifest from there:

brew tap transaction-science/tap https://git.transaction.science/Transaction-Science/homebrew-tap
brew install --cask wai-quantum-desktop

scoop bucket add transaction-science https://git.transaction.science/Transaction-Science/scoop-bucket
scoop install wai-quantum-desktop

Each build runs what it made before it is attached: the bundled app's check, and its update-status, which names the installer a copy came from (none, for a copy cargo built or the portable archive's), the macOS app's code signature and the disk image's checksums, the AppImage, and the Debian package unpacked. The bundler is pinned (cargo install --locked tauri-cli --version 2.12.3), and the builds are, with UPDATER_CONFIG {} unless the release signs updates:

cargo tauri build --ci --target "$t" --bundles app,dmg --features metal --config "$UPDATER_CONFIG" -- --locked    # macOS
cargo tauri build --ci --target "$t" --bundles appimage,deb,rpm --config "$UPDATER_CONFIG" -- --locked             # Linux
cargo tauri build --ci --target $t --bundles nsis --config $updaterConfig '--' --locked                            # Windows (PowerShell)

Which copies update themselves. A copy looks for updates only when it was built with the release's public key and came from its own installer: the macOS app (moved out of its disk image), the AppImage, the Debian or RPM package, or the Windows installer. A copy built from source, or unpacked from the portable archive by a package manager, says nothing of updates and is updated the way it came. The app asks one address, https://wai.transaction.science/quantum-studio-desktop/latest.json, which the website serves. Each signed release attaches its own latest.json, and the website takes it from that release when it is next deployed (scripts/sync-desktop-update.sh <version> in the website's repository, which refuses a manifest for an older version than the one it serves, or one whose updates are not on that version's release). The check is a plain download of that file, and sends nothing else. An update is refused unless its signature verifies with the key in tauri.conf.json (plugins.updater.pubkey) and names the version the manifest announces (requireSignedVersion), so a manifest cannot pair a newer number with an older build. Before attaching anything, the release runs the built app's verify-update FILE SIG VERSION on every update it signed, which makes the same check with the same key.

What the owner sets up. Until then a release is unsigned and installers are all it makes: the macOS app is signed ad hoc and not notarised (the cask says how to open it the first time), and no copy updates itself.

1. The update key, made once on a machine you trust (it asks for a password; the private key goes to the file and is never printed), then the public key into the app:

   cargo tauri signer generate -w ~/.tauri/wai-quantum-desktop.key
   

   Put the one line of ~/.tauri/wai-quantum-desktop.key.pub in tauri.conf.json as plugins.updater.pubkey, and commit that. The private key never goes in the repository.

2. The forge secrets (the repository's Settings, then Actions, then Secrets). The release reads each one only when it is set, and the log says which steps it skipped:

   Secret	What it holds	Without it
   WAI_QUANTUM_DESKTOP_UPDATER_KEY	the text of ~/.tauri/wai-quantum-desktop.key	no update is signed, and no latest.json is written
   WAI_QUANTUM_DESKTOP_UPDATER_KEY_PASSWORD	its password	(needed if the key has one)
   APPLE_SIGNING_IDENTITY	the Developer ID Application identity, e.g. Developer ID Application: NAME (TEAMID)	the app is signed ad hoc
   APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD	that certificate as a .p12 file in base64, and its password (not needed when the macOS runner's keychain already holds the identity)
   APPLE_API_ISSUER, APPLE_API_KEY, APPLE_API_KEY_P8	an App Store Connect API key for notarisation: its issuer, its key ID and the .p8 file's text	not notarised
   APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID	instead of the API key: an Apple ID, an app-specific password and the team

   A key in the secret with no public key in tauri.conf.json stops the release, since no copy could check what it is offered.