7.5 KiB
Swift App Handoff
Decision
There is no Swift-to-Rust data migration, but the old apps update straight
into the new one (Kit, 2026-11-02: "gotta get everyone over"). 2.3.1 and Swift
Hex both run Sparkle 2.9.4 with the same EdDSA key, so their feeds offer the
released Hex.app and Install Update replaces the old app with it. See
Legacy Update.
- Do not import Swift settings, history, audio, models, or other data.
- Nothing installs without the user's Install Update click, and nothing is
deleted. Once setup is ready and the listener starts,
anomaly.hexasks a running old Hex (the retired bundle IDs below) to quit, so the two never answer the same shortcut. - Do not adopt the Swift bundle identifier.
- Do not move or copy existing Rust settings, models, or history.
- Narrow TCC exception: when
anomaly.hexshows an untrusted Accessibility, Screen Recording, or System Audio Recording permission row (or the user clicks"Still grey? Fix it"), it may runtccutil resetagainst retired Hex bundle identifiers (com.kitlangton.hex2,com.kitlangton.Hex,com.kitlangton.Hex.debug) so System Settings does not list duplicate Hex rows that shadow the new grant. - New Rust users complete ordinary setup and download their selected local model.
Separate Identities
The Rust app is called Hex, packaged as Hex.app, with
bundle identifier com.kitlangton.hex2 and executable hex. Its Application Support
root is hex. The supported platform remains Apple silicon with
macOS 15 or newer. The new bundle identity requires fresh macOS permission grants;
changing the display name alone does not change signing ownership.
Kit's personal Developer ID Application certificate (team QC99C9JE59) is approved
for this app. Explicitly provide HEX_TEAM_ID and the matching
HEX_NOTARY_PROFILE before release; an Anomaly signing account is not required.
Swift retains its own bundle identity, sandbox data, and S3 update feed. Intel and macOS 14 users can continue using Swift without an incompatible-install nag.
On case-insensitive volumes, the two app filenames can conflict. Finder may ask whether to replace an existing app during manual installation; that remains the user's choice, not an automated migration. The development installer refuses to replace a destination whose bundle identifier is not the Rust identifier. Users should quit the old app before dictating in the new one to avoid running two global hotkey listeners.
Legacy Update
Sparkle 2.9.4 installs the new app over 2.3.1 (HEX.app or Hex.app) and Swift
Hex because:
- It finds the app. The ZIP's
Hex.appmatches the old app's file name or itsCFBundleNameplus.app(SUInstaller.m). - The key passes. The old app has
SUPublicEDKey, so Sparkle refuses an update without one;app/Info.plistkeeps the same key, and the ZIP is signed with its private half. A passing EdDSA check is enough when the team differs (SUUpdateValidator.m). - It is not a downgrade. The new
CFBundleVersion(30300 and up) exceeds 2.3.1's 20301 and Swift's 92. - The swap is not atomic. The team differs, so Sparkle moves the old app aside and the new one in, then opens it.
Each feed gets one item whose enclosure is the release's
Hex-<version>-macos-arm64.zip, with sparkle:edSignature from the old key,
sparkle:version the new CFBundleVersion, sparkle:minimumSystemVersion
15.0, and sparkle:hardwareRequirements arm64. Macs that cannot run the new
Hex keep their last compatible release. The new Hex starts fresh: new
permissions, model, and shortcut.
Legacy Notice (superseded)
Swift 0.8.5/build 92 already ships a dismissible link to the Rust app. This Rust release does not publish another Swift build or change its S3 feed. The optional feed-only notice below remains a separate future action.
Prefer a website-only Sparkle update,
not another custom Swift popup or bridge build. The shipping v0.8.5 source pins
Sparkle 2.9.4, which supports both the informational item and platform gates.
After the new signed app and download page are live, add one item to the existing Swift S3 appcast while preserving every existing release and artifact:
link:https://github.com/anomalyco/hex, the public download page.sparkle:version: reserve 93 if still unused; it must exceed installed build 92.sparkle:shortVersionString: the public Rust release advertised when the notice is published; do not copy a stale version from this plan.sparkle:minimumSystemVersion: 15.0.0.sparkle:hardwareRequirements: arm64.sparkle:minimumUpdateVersion: 92.- Embedded release notes explain separate installation, new permissions and model setup, no settings/history transfer, and the same-name app-file collision.
- Omit
enclosureentirely, including delta enclosures. Without a download URL, Sparkle treats the item as informational. No Rust installer goes in this feed.
The standard button is Learn More..., which opens the page and closes the window. Skip This Version persists a dismissal. Remind Me Later, closing the window, or opening the website does not permanently dismiss the notice. Manual Check for Updates can show a skipped notice again. This is not a guaranteed one-time custom modal, and appcast text cannot rename the standard buttons.
OS and architecture gates work without an enclosure in Sparkle 2.9.4. Older Sparkle versions may ignore the architecture/minimum-update gates; unsupported users may still reach an informational page, but never an automatic install. Keep requirements explicit on that page and retain Swift build 92 for compatible legacy updates. Do not mark the notice critical or redirect the old feed.
Before publication, verify the actual distributed Swift bundle, automatic and manual checks, skip/remind behavior, and supported/unsupported Mac configurations. The announcement is only a proposal until the new signed artifact is available and these behaviors are validated.
Releases
Prepare and publish Rust through scripts/release-app.sh, with identity checks
from scripts/validate-app.sh. Publish immutable artifacts before the R2 feed.
The manual DMG contains Hex.app; the Sparkle ZIP keeps the old Rust HEX.app
archive name. Sparkle 2.9.4 uses case-sensitive filenames or matching bundle IDs
to discover an update, so changing both at once would hide the update payload
from 2.0.x installations. Both artifacts contain the same signed, stapled app.
Validate the approved signing identity and installation behavior before publishing.
Do not assume permissions or login-item registrations survive the identity change.
Publish the legacy informational feed item independently after the new artifact is available. A Swift rebuild is unnecessary unless the stock Sparkle UI proves insufficient. No transition archive, cross-feed payload, preference importer, or migration rollback is needed.
GitHub Handoff
Keep the old Swift repository's history, issues, and releases. A prominent README
notice and repository website link can direct users to anomalyco/hex; archive
the old repository only after the handoff is complete and explicitly approved.
Do not overwrite its history with Rust source. An actual repository transfer is
a separate decision because anomalyco/hex already exists; GitHub does not merge
the two repositories' stars, issues, and histories automatically.