Release bundles, smoke test, Homebrew formula and release workflow

[krishhgg]

PR 3 of 4 for packaging. PRs 1 (#34) and 2 (#35) are merged, so this targets main. It builds the release bundles, tests them, renders the Homebrew formula and adds the workflow that publishes a release from a tag.

What a user gets

• 2 bundles, picked by the formula. brew install picks one from MacOS.full_version.
  • The macOS 26 bundle (66.9 MB) is for macOS 26.2 and later. Its MLX build has the neural-accelerator kernels that make sys1d's round 3 defaults fast.
  • The macOS 14 bundle (45.1 MB) covers macOS 14.0 through 26.1 with the standard MLX build.
• Bundle layout. bin/sys1rust, lib/ with libmlx.dylib, libjaccl.dylib and mlx.metallib from the official mlx-metal 0.32.2 wheels, plus LICENSE, NOTICE and licenses/. The binary finds its libraries through @executable_path/../lib, so it runs through Homebrew's bin symlink.
• License notices. licenses/ carries the Rust crate licenses, MLX's license and 16 pinned texts for third-party code compiled into the MLX libraries. Among them are nlohmann/json, gguflib, metal-cpp, PocketFFT and PyTorch's fp8 conversion. NOTICE names each text and explains the 2 exclusions. fmt's license exempts object code, and ThreadPool's zlib terms ask for a notice only in source copies.
• A brew services entry that runs sys1rust serve at login.

What build.sh checks

packaging/build.sh macos26|macos14 OUT fails unless:

• Rust matches packaging/rust-toolchain-version (1.95.0).
• The wheel matches its sha256 in packaging/mlx-wheels.lock.
• Every vendored license text exists and NOTICE names it.
• The binary links only into the bundle and the OS, with exactly 1 rpath.
• No Mach-O file needs a newer macOS than the bundle's target.
• codesign --verify passes.
• --version prints the expected string.

The smoke test

packaging/smoke.py starts the bundle's serve --offline --port 0 and sends the 24 smoke requests (120 questions). It compares each answer with bench/reference/typed-decisions/smoke.jsonl using bench/harness/compare.py's rules. Each reply must match the reference's shape, as in live.rs: the same question ids, answer fields, probability labels and legend, in order. Probabilities and confidences must be finite and in [0, 1], and confidences must stay within the same 0.05 drift limit. It also requires a clean shutdown on SIGINT, and it never leaves a server running, even when interrupted during startup.

On a base M5, both bundles had 0 failures. The largest probability drift was 0.0008 (macOS 26 bundle) and 0.0009 (macOS 14 bundle).

Homebrew

• packaging/sys1rust.rb.in plus render_formula.sh render the formula for a tag and the 2 tarball hashes.
• A local tap install from a rendered formula passed brew install, brew test and the smoke test through Homebrew's path.
• brew style and brew audit --strict --online are clean.

The release workflow

.github/workflows/release.yml runs on v* tags. A pull request that touches packaging/ or the workflow runs only the build and smoke jobs.

• build (macos-26) checks the tag against the workspace version and builds both bundles.
• smoke runs the macOS 26 bundle on macos-26 and the macOS 14 bundle on macos-15. Each job pulls typed-decisions into a cached HF_HUB_CACHE, then runs smoke.py. GitHub retires its macos-14 runner on 2026-11-02, so no job uses it. macos-15 still runs the macOS 14 bundle on an OS older than 26.2, which is the case that bundle exists for.
• publish (tags only):
  • It checks that TAP_TOKEN can push to the tap, with git push --dry-run, before anything goes public.
  • It publishes the release with SHA256SUMS. A -rcN tag makes a prerelease and leaves the tap alone.
  • A final tag then commits the rendered formula to krishhgg/homebrew-tap.
  • Reruns are safe. A leftover draft from a cancelled run stops the job with instructions, since deleting it automatically could race a manual publish. A published release is accepted only when its tarballs and SHA256SUMS match this run. A tap with a newer version is left alone. Publish jobs from different tags share a concurrency group.

packaging/RELEASE.md is the checklist. It covers the local strict suite in a dedicated cache holding only the pinned snapshots, smoke on both bundles, an rc tag, a throwaway local tap install, the final tag, and the expired-token recovery.

Prerequisites (done)

• The tap repo krishhgg/homebrew-tap exists.
• The TAP_TOKEN secret is set, a fine-grained token with contents read and write on that repo only.

Tests

• Both bundles built and smoke-tested on a base M5 as above. A build from a checkout path containing spaces works.
• actionlint 1.7.12 with shellcheck is clean on the workflow.
• The publish steps ran against a fake gh and a local git server, 10 release cases plus the tap cases:
  • a run cancelled partway through upload, and a draft published by hand during the rerun
  • an expired token (fails before publishing)
  • a read-only token
  • a newer formula already in the tap
  • a rerun with no changes
• render_formula.sh gives identical output with GNU and BSD tools, including URLs that contain &, | and \.
• This PR's first workflow run passed on GitHub's hosted runners. The build took 5 minutes. Both smoke jobs downloaded typed-decisions, ran on the runner's paravirtual Metal GPU with MLX's gemms, and had 0 failures with a largest drift of 0.0010. The macOS 14 bundle ran on macOS 15.7.9 and the macOS 26 bundle on 26.6.2.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; both previous findings are addressed and no new blocking issue was found.

What we checked:

• Correct replies rejected by order: The strict test already requires the same ordered fields and probability labels. The smoke test now follows that contract.
• Valid probabilities rejected: The server normalizes probabilities and clamps entropy confidence to [0, 1]. The new bounds match those calculations.

Summary

Adds two macOS release bundles, license notices, a Homebrew formula, and a workflow that builds, smoke-tests, and publishes tagged releases.

• The latest changes make smoke.py check reply shape, missing fields, and confidence differences.
• The release checklist now states the GPU requirement for the strict suite.
• Both previous findings are addressed. No new actionable issues were found.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Trigger["Packaging PR or version tag"] --> Build["Build both macOS bundles"]
  Build --> Smoke14["Smoke macOS 14 bundle on macOS 15"]
  Build --> Smoke26["Smoke macOS 26 bundle on macOS 26"]
  Smoke14 --> Gate{"Tag and both tests pass?"}
  Smoke26 --> Gate
  Gate -->|Yes| Publish["Publish release and checksums"]
  Publish --> Final{"Final release?"}
  Final -->|Yes| Tap["Update Homebrew formula"]
  Final -->|No| RC["Keep prerelease out of tap"]

Loading

_{Reviews (2) · Last reviewed commit: "Require every reference field in the smo..."}