Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 17 Packages Wiki Activity Actions 187
open-standards/wai/wai-quantum-desktop/README.md
Transaction Science 2257b320fc Quantum Studio: a job on your own hardware outlives the window 
A run on one of the person's providers waited inside the desktop app for up
to two hours, holding the Studio, and then cancelled the job, giving up its
place in a device's queue. The app now writes the job down before it sends
it, with the command line's records of jobs on a provider (#581), and asks
after it by its id.

- wai-quantum-desktop: run_on_provider answers within ten seconds, done or
  still running with its id; provider_job asks after a job once or cancels
  it; provider_jobs lists the jobs sent, asking no provider.
- Quantum Studio: while a job waits, Cancel cancels it at the provider and
  "Wait in the background" leaves it there and frees the Studio. A job left
  waiting, from this window or an earlier one, is followed while the app is
  open, and its result goes to the history when it finishes. Your jobs lists
  every job sent. A check that fails during the wait does not end it.
- The tests: the app's queued job answered by its id, sealed with the app's
  key, the same answer after, and cancelled only when asked; the page's
  wait, cancel, cancel-after-finish, failed check, background and reopened
  window. The studio workflow names the new app test on every leg.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-02 22:19:02 -05:00

9 KiB
Raw Permalink Blame History

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. A run is written down before it is sent, with the command line's records of jobs on a provider, so a job in a long queue outlives the window: while it waits, Cancel cancels it at the provider and Wait in the background leaves it there and frees the Studio. A job left waiting, from this window or one closed earlier, is followed while the app is open, and its result goes to the history when it finishes; Your jobs lists every job sent, and wai-quantum providers collect pj-… collects one from a terminal. Waiting never cancels a job.
  • 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.