docs(release): wire pre-release-check + RELEASING.md + comments to new flow

- pre-release-check: clarify that swift xcframework is built here as a
  sanity check only; the shipping zip comes from release_swift.yml on PR
  CI. Same-host determinism check kept (catches stale caches).

- RELEASING.md: rewrite for the two-phase version bump. Local
  prepare-release does versions only (no Xcode required); PR CI's
  release_swift.yml bakes the Swift xcframework SHA into Package.swift on
  the release branch and uploads the zip to a draft GitHub release. Tag
  CI just promotes the draft. New 'Why PR-CI builds the Swift xcframework'
  section documents the determinism trade-off the old local-baked flow
  kept hitting.

- Package.swift, bump_version.py, zip_xcframework.sh: comments updated to
  match the new flow (releaseChecksum is written by PR CI, not local;
  zip_xcframework's determinism is now same-host sanity, not cross-host
  reproducibility).

Author: dignifiedquire

Makefile.toml

@@ -579,7 +579,7 @@ dependencies = ["format-check", "clippy", "docs", "test-rust"]
 # ---------------------------------------------------------------------------
 
 [tasks.pre-release-check]
-description = "Local dry-run of every release artifact build (no uploads, no network publishes). Run before tagging."
+description = "Local dry-run of every release artifact build (no uploads, no network publishes). Run before opening the release PR. Swift xcframework + zip is exercised here as a sanity check but the published release uses the zip that release_swift.yml builds on PR CI — local SHAs do NOT need to match CI."
 script_runner = "@shell"
 script = '''
 set -eu
@@ -589,16 +589,20 @@ if [ "$(uname -s)" != "Darwin" ]; then
   exit 1
 fi
 
-echo "==> swift: build + verify layout + iOS consumer build + deterministic zip"
+echo "==> swift: build + verify layout + iOS sim test + same-host zip determinism"
 cargo make swift-xcframework >/dev/null
 cargo make verify-swift-xcframework >/dev/null
 cargo make verify-swift-consumer >/dev/null
 bash scripts/release/zip_xcframework.sh
 H1=$(shasum -a 256 IrohLib.xcframework.zip | awk '{print $1}')
 bash scripts/release/zip_xcframework.sh
 H2=$(shasum -a 256 IrohLib.xcframework.zip | awk '{print $1}')
-[ "$H1" = "$H2" ] || { echo "swift zip non-deterministic: $H1 vs $H2" >&2; exit 1; }
-echo "  ok (sha256=$H1)"
+# Same-host determinism: the build must produce identical bytes when run twice
+# on the same machine. Catches stale caches / non-deterministic flags. Doesn't
+# attempt cross-host match — release_swift.yml is the only build whose zip
+# actually ships.
+[ "$H1" = "$H2" ] || { echo "swift zip non-deterministic on this host: $H1 vs $H2" >&2; exit 1; }
+echo "  ok (sha256=$H1, ships from CI not from here)"
 
 echo "==> python: maturin build + wheel consumer smoke"
 PYVENV=$(mktemp -d)/venv

Package.swift

@@ -19,10 +19,11 @@ import Foundation
 // to the release zip. Set IROH_FORCE_REMOTE_XCFRAMEWORK to force the release
 // zip even in a built checkout.
 //
-// The two release literals below are the only things `cargo make
-// prepare-release` rewrites (per Phase 6 plan, CI never writes to main).
-// Local prepare-release builds a deterministic xcframework zip, shasums it,
-// and bakes both values into this manifest in the release commit.
+// `releaseTag` is rewritten locally by `cargo make prepare-release <V>`.
+// `releaseChecksum` is rewritten on PR CI by `release_swift.yml` (one bot
+// commit on the release branch, marked `[skip swift-release]`), so the value
+// here always matches the IrohLib.xcframework.zip attached to the GitHub
+// release — never a cross-host determinism game.
 let releaseTag = "v1.0.0"
 let releaseChecksum = "514b147f7965fe17acaece9a1157cf9421463b6c9282224983e871ea868b86ef"
 

RELEASING.md

@@ -1,28 +1,29 @@
 # Releasing iroh-ffi
 
-A release ships a new version of the iroh-ffi crate's surface to every
-binding host (npm, PyPI, GitHub Releases for Swift) plus refreshed docs on
-GitHub Pages. The tag is the trigger — pushing `v<VERSION>` fans out to all
-four publish workflows independently.
+A release ships a new version of the iroh-ffi crate's surface to every binding
+host (npm, PyPI, Maven Central, GitHub Releases for Swift) plus refreshed docs
+on GitHub Pages. The tag is the trigger — pushing `v<VERSION>` fans out to all
+publish workflows independently.
 
-The repo manifest stays **self-consistent at every commit**: the version
-literals in `Cargo.toml`, `iroh-js/package.json`, and `Package.swift` (tag +
-checksum) are written by a local script before the release PR is opened. CI
-never writes to `main`.
+The repo manifest stays self-consistent at every commit. Version literals in
+`Cargo.toml`, `iroh-js/package.json`, etc. are written by a local script
+before the release PR is opened; the Swift xcframework SHA-256 in
+`Package.swift` is written by PR CI (one bot commit on the release branch).
+CI never writes to `main`.
 
 ## Prerequisites
 
-- macOS workstation with Xcode (the prepare-release script builds the Apple
-  xcframework to compute the SwiftPM checksum).
+- Local shell with `cargo`, `yarn`, and Python 3 (no Xcode needed —
+  prepare-release no longer builds the xcframework).
 - Push rights on the repo + the relevant publisher accounts (npm
   `@number0/iroh`; PyPI trusted publisher for `iroh`; Sonatype Central for
-  `computer.iroh` once Maven publishing is wired).
+  `computer.iroh`).
 - `main` is green at the commit you want to release from.
 
 ## Steps
 
-0. **Local dry-run** (recommended). Validates every artifact builds without
-   touching any registry:
+0. **Local dry-run** (recommended, macOS only — needs Xcode for the swift slot).
+   Validates every artifact builds without touching any registry:
 
    ```sh
    # the armored private key (same contents as the SIGNING_KEY CI secret)
@@ -31,37 +32,47 @@ never writes to `main`.
    cargo make pre-release-check
    ```
 
-   Builds the Swift xcframework + deterministic zip, the Python wheel,
-   the napi addon + `npm publish --dry-run`, and `gradle
-   publishToMavenLocal`. Catches config typos, signing failures, manifest
-   errors before the real publish.
+   Builds the Swift xcframework (sanity check only — the published zip
+   comes from PR CI, not here), the Python wheel + import smoke, the napi
+   addon + `npm publish --dry-run`, and `gradle publishToMavenLocal` +
+   JNA-from-per-platform-staged smoke. Catches config typos, signing
+   failures, manifest errors before the real publish.
 
-1. **Prepare the release branch + commit.**
+1. **Bump versions on a release branch.**
 
    ```sh
    git checkout main && git pull
    cargo make prepare-release 1.0.0-rc.1     # no leading v
-   ```
-
-   This rewrites the version literals, refreshes lockfiles, builds a
-   deterministic `IrohLib.xcframework.zip`, and bakes its SHA-256 into
-   `Package.swift`. Inspect the diff (`git diff`) — expected files only:
-   `Cargo.toml`, `Cargo.lock`, `iroh-js/package.json`, `iroh-js/yarn.lock`,
-   `Package.swift`.
-
-2. **Open the release PR.**
-
-   ```sh
    git checkout -b release/v1.0.0-rc.1
    git commit -am "chore(release): v1.0.0-rc.1"
    git push -u origin release/v1.0.0-rc.1
    gh pr create --base main --fill --title "chore(release): v1.0.0-rc.1"
    ```
 
-   Get all CI green on the PR.
+   `prepare-release` only rewrites version literals + lockfiles. Inspect
+   the diff (`git diff`) — expected files only: `Cargo.toml`, `Cargo.lock`,
+   `iroh-js/package.json` + `iroh-js/Cargo.toml`, `iroh-js/yarn.lock`,
+   `pyproject.toml`, `kotlin/lib/build.gradle.kts`, `Package.swift`
+   (releaseTag only — the checksum is filled in by CI in step 2).
 
-3. **Merge to `main`.** Squash or merge-commit — both work; whichever lands
-   keeps Package.swift consistent.
+2. **Wait for PR CI to bake the Swift xcframework SHA.**
+
+   `release_swift.yml` fires on push to `release/v*` branches. It builds
+   the xcframework on a self-hosted macOS runner, runs the verify gates
+   (layout + iOS sim test), zips deterministically, and:
+   - commits `chore(release): bake Swift xcframework SHA <hex>
+     [skip swift-release]` to the release branch (overwrites the
+     placeholder checksum in `Package.swift`);
+   - uploads `IrohLib.xcframework.zip` to a draft GitHub release named
+     `v1.0.0-rc.1`.
+
+   Review the bot's commit + the draft release asset (downloadable from
+   the GitHub Releases page) before merging. The SHA in `Package.swift`
+   is exactly the SHA of the zip on the draft release — no cross-host
+   determinism game.
+
+3. **Merge to `main`.** Squash or merge-commit; both keep `Package.swift`
+   consistent with the draft release.
 
 4. **Tag the merge commit and push.**
 
@@ -75,32 +86,43 @@ never writes to `main`.
 
    | Workflow | Publishes |
    |---|---|
-   | `release.yml` | GitHub Release + per-OS binary assets + `IrohLib.xcframework.zip` |
-   | `ci_js.yml` `publish` | `@number0/iroh` to npm (`--provenance`, `NPM_TOKEN`) |
-   | `wheels.yml` `publish` | `iroh` wheels to PyPI (Trusted Publishing / OIDC — no token) |
+   | `release.yml` | promotes the draft GH release v<version> to published; uploads per-OS C lib archives |
+   | `ci_js.yml` `publish` | `@number0/iroh` to npm (`--provenance`, OIDC) |
+   | `wheels.yml` `publish` | `iroh` wheels to PyPI (OIDC) |
+   | `release.yml` `build-and-publish-kotlin` | `computer.iroh:iroh` to Maven Central |
    | `docs.yml` | GitHub Pages site refresh |
-   | _(future)_ `release.yml` `build-and-publish-kotlin` | Maven Central `computer.iroh:iroh` (blocked on #147) |
 
-   If any publish fails, fix and re-tag with the next patch version (do not
-   re-use a tag).
+   The Swift xcframework zip is **not** rebuilt at tag time — `release.yml`
+   `create-release` just promotes the PR-CI-built draft.
+
+   If any publish fails, fix and re-tag with the next patch version (do
+   not re-use a tag).
 
-## Why local-only prepare
+## Why PR-CI builds the Swift xcframework (not local, not tag-CI)
 
 Binary SwiftPM packages need the manifest checksum to match the uploaded
-zip byte-for-byte. We use a deterministic zip recipe
-(`scripts/release/zip_xcframework.sh`: fixed mtimes + sorted file list + no
-zip extra fields) so the local zip and the one rebuilt by `release.yml`
-hash identically. This lets `Package.swift` carry the correct checksum
-from the release commit forward — no CI write-back to `main`, no
-intermediate broken state. Matches the firebase-ios-sdk / Sentry-Cocoa
-release pattern for binary SwiftPM packages.
+zip byte-for-byte. The previous flow built the xcframework locally during
+`prepare-release`, baked the SHA into `Package.swift`, then rebuilt on
+tag-CI and expected the SHA to still match — which required cross-host
+build determinism (matching Xcode patch version, macOS SDK, rustc, cargo
+deps, etc.). That kept failing in practice.
+
+Single source of truth: PR CI builds the zip once, bakes its SHA into the
+PR, uploads to a draft release. Tag CI just promotes the draft. The SHA
+in `Package.swift` is the SHA of the bytes on the release — they were
+literally the same zip. No build-environment skew can break consumers.
+
+The trade-off is that the release branch picks up one bot commit
+(`bake Swift xcframework SHA <hex>`), which is reviewable in the PR diff.
+`[skip swift-release]` in the commit message prevents the workflow from
+re-firing on its own output.
 
 ## One-time publisher setup (per host)
 
-- **npm** — `NPM_TOKEN` repo secret with publish rights on `@number0/iroh`.
+- **npm** — Trusted Publishing configured at npmjs.com (no token).
 - **PyPI** — register a trusted publisher at
   <https://pypi.org/manage/account/publishing/>: project `iroh`, owner
-  `n0-computer`, repository `iroh-ffi`, workflow `wheels.yml`. No long-lived
-  token needed. Until registered, the first publish job will fail loudly.
-- **Maven Central** _(future, blocked on #147)_ — claim `computer.iroh`
-  namespace via DNS TXT on `iroh.computer`; GPG signing key; OSSRH creds.
+  `n0-computer`, repository `iroh-ffi`, workflow `wheels.yml`.
+- **Maven Central** — `computer.iroh` namespace claimed via DNS TXT on
+  `iroh.computer`; armored PGP key in `SIGNING_KEY` secret; Sonatype
+  Central API creds.

scripts/release/bump_version.py

@@ -1,11 +1,14 @@
 #!/usr/bin/env python3
-"""Rewrite the three version literals across the repo as a single source of truth.
-
-Called by `cargo make prepare-release <VERSION>` in two passes:
-  1. Pass 1 (just VERSION):  bumps Cargo.toml [package].version,
-     iroh-js/package.json version, and Package.swift releaseTag.
-  2. Pass 2 (--checksum HEX): writes Package.swift releaseChecksum once the
-     deterministic xcframework zip has been built and shasum'd.
+"""Rewrite the version literals across the repo as a single source of truth.
+
+Two entry points:
+  1. `cargo make prepare-release <V>` calls this with just VERSION to bump
+     Cargo.toml [package].version, iroh-js/{Cargo.toml,package.json}, all the
+     iroh-js/npm/*/package.json sub-packages, pyproject.toml,
+     kotlin/lib/build.gradle.kts coordinates, and Package.swift releaseTag.
+  2. release_swift.yml (PR CI) calls this with --checksum HEX once it has
+     built the xcframework and shasum'd the deterministic zip, to write
+     Package.swift releaseChecksum.
 
 Pure deterministic text/JSON transforms — no model, no network (org Rule 5).
 """

scripts/release/zip_xcframework.sh

@@ -1,13 +1,14 @@
 #!/bin/bash
 set -eu
 
-# Deterministic zip of Iroh.xcframework — produces byte-identical output
-# regardless of host or wall clock. Used by:
-#   - `cargo make prepare-release` (local) so it can compute a checksum that
-#     will match what CI uploads, and bake it into Package.swift in the same
-#     PR (CI never rewrites main, per the Phase 6 plan).
-#   - `.github/workflows/release.yml` `build-and-publish-swift` so the
-#     uploaded asset matches the just-committed Package.swift checksum.
+# Same-host deterministic zip of Iroh.xcframework — produces byte-identical
+# output across multiple runs on the same machine (catches stale caches and
+# non-deterministic flags). Used by:
+#   - release_swift.yml (PR CI) — builds the zip whose SHA-256 gets baked
+#     into Package.swift on the release branch and uploaded to a draft GH
+#     release. That single CI build is the only build whose bytes ship.
+#   - cargo make pre-release-check (local) — sanity check that the build is
+#     reproducible-on-this-host; local SHAs don't need to match CI's.
 #
 # Determinism recipe:
 #   - normalize all mtimes to 1980-01-01 (the zip-format epoch);