ci(release): the darwin-arm64 binary is built on a macOS runner and both publishes are gated on it; the per-push macOS build job

Author: Winterrks

.github/workflows/ci.yml

@@ -1,6 +1,33 @@
 name: ci
 on: [push, pull_request]
 jobs:
+  # --- P9a-4: the SAME macOS build as release.yml's `build-platform`, minus the tag pin, on EVERY
+  # push -- so a broken darwin build fails here, before a `v*` tag ever exists to discover it at
+  # publish time. Runs the smoke's EXECUTE path (real `--version` spawn of the just-built binary)
+  # rather than the SKIP path the two ubuntu `pack-smoke*` jobs below take on this same publishable
+  # package (M1: `os`/`cpu` mismatch there is expected and permanent, never a reason to fail). This
+  # job never publishes anything -- `release-gates.test.ts` pins that alongside every other job here.
+  build-platform:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+      - name: "assert a REAL macOS arm64 runner (P9a-4) -- never trust the `macos-15` label alone"
+        run: |
+          set -euo pipefail
+          UNAME_S="$(uname -s)"
+          UNAME_M="$(uname -m)"
+          if [ "$UNAME_S" != "Darwin" ] || [ "$UNAME_M" != "arm64" ]; then
+            echo "build-platform: expected Darwin/arm64, got $UNAME_S/$UNAME_M -- refusing to build the darwin-arm64 binary here" >&2
+            exit 1
+          fi
+      - uses: oven-sh/setup-bun@v2
+      - uses: pnpm/action-setup@v4
+        with: { version: 10 }
+      - run: pnpm install
+      - run: bun run scripts/build-runtime.ts --platform-package
+      - run: ./packages/platform/darwin-arm64/bin/winter --version
+      - run: bun run scripts/smoke-installed.ts --runtime=bun   # the EXECUTE path (P9a-5): os/cpu match here
+
   build:
     runs-on: ubuntu-latest
     steps:

.github/workflows/release.yml

@@ -11,13 +11,70 @@ on:
     tags: ["v*"]
   workflow_dispatch: {}
 jobs:
+  # --- P9a-3/P9a-4: THE DARWIN-ARM64 BINARY, BUILT ONLY ON A MATCHING RUNNER --------------------
+  #
+  # `bun build --compile` targets the CURRENT host -- it does not cross-compile (M1/P9a-4) -- so the
+  # darwin-arm64 binary can only ever be produced on a `darwin`/`arm64` runner, and this job's FIRST
+  # step asserts that with `uname` rather than trusting the `macos-15` label (a label names an image,
+  # not a guarantee of what `uname` reports on it). Both publish jobs `needs: build-platform` and
+  # download this job's artifact rather than rebuilding -- GitHub Actions strips the executable bit
+  # from artifact uploads, which is why this job tars the binary and the publish jobs untar it and
+  # restore the bit explicitly, verifying identity (Mach-O arm64, matching sha256) before either
+  # registry ever sees it. This job never runs a publish command -- `release-gates.test.ts` pins that.
+  build-platform:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+      - name: "assert a REAL macOS arm64 runner (P9a-4) -- never trust the `macos-15` label alone"
+        run: |
+          set -euo pipefail
+          UNAME_S="$(uname -s)"
+          UNAME_M="$(uname -m)"
+          if [ "$UNAME_S" != "Darwin" ] || [ "$UNAME_M" != "arm64" ]; then
+            echo "build-platform: expected Darwin/arm64, got $UNAME_S/$UNAME_M -- refusing to build the darwin-arm64 binary here" >&2
+            exit 1
+          fi
+      - uses: oven-sh/setup-bun@v2
+      - uses: pnpm/action-setup@v4
+        with: { version: 10 }
+      - run: pnpm install
+      - run: bun run scripts/build-runtime.ts --platform-package
+      - name: "the binary's own --version matches the tag being published (workflow_dispatch has no tag: skipped)"
+        run: |
+          set -euo pipefail
+          BIN=packages/platform/darwin-arm64/bin/winter
+          ACTUAL="$("$BIN" --version)"
+          echo "build-platform: binary reports --version $ACTUAL"
+          case "${GITHUB_REF:-}" in
+            refs/tags/v*)
+              EXPECTED="${GITHUB_REF#refs/tags/v}"
+              if [ "$ACTUAL" != "$EXPECTED" ]; then
+                echo "build-platform: binary reports --version $ACTUAL but the pushed tag names $EXPECTED" >&2
+                exit 1
+              fi
+              ;;
+            *) echo "build-platform: no v* tag on this ref (workflow_dispatch) -- version-vs-tag check skipped" ;;
+          esac
+      - run: shasum -a 256 packages/platform/darwin-arm64/bin/winter | tee winter-darwin-arm64.sha256
+      - run: tar -cf winter-darwin-arm64.tar -C packages/platform/darwin-arm64 bin/winter
+      - uses: actions/upload-artifact@v4
+        with:
+          name: winter-darwin-arm64
+          path: |
+            winter-darwin-arm64.tar
+            winter-darwin-arm64.sha256
+          retention-days: 7
+
   # --- TWO REGISTRIES, TWO JOBS (P7a pre-publish item 5; user ruling 2026-09-08) ------------------
   #
   # GitHub Packages first, npm second, and SEPARATE jobs on purpose: the npm leg needs a secret this
   # repository may not have, and a missing `NPM_TOKEN` must never block the GitHub Packages publish.
   # `needs:` makes the dependency explicit -- npm runs only if GitHub Packages SUCCEEDED, so the two
   # registries can never disagree about which versions exist because the first leg failed halfway.
+  # BOTH jobs now also `needs: build-platform` (P9a-4): the darwin-arm64 binary this workflow ships
+  # must exist, on the real artifact, before either registry publish begins.
   publish:
+    needs: build-platform
     runs-on: ubuntu-latest
     # R-7-1: GitHub Packages, scope @yanlinglabs. `contents: read` is the default job permission
     # this repeats explicitly; `packages: write` is the one elevated grant a publish needs and the
@@ -47,6 +104,20 @@ jobs:
           registry-url: "https://npm.pkg.github.com"
           scope: "@yanlinglabs"
       - run: pnpm install
+      # P9a-4: restore the darwin-arm64 binary `build-platform` produced, and VERIFY it before this
+      # job's own gates or the publish step ever run -- a downloaded GitHub Actions artifact loses its
+      # executable bit, so this is not optional ceremony; without `chmod +x` the smoke below fails.
+      - uses: actions/download-artifact@v4
+        with: { name: winter-darwin-arm64 }
+      - name: "restore + verify the platform binary before anything downstream can publish it"
+        run: |
+          set -euo pipefail
+          tar -xf winter-darwin-arm64.tar -C packages/platform/darwin-arm64
+          BIN=packages/platform/darwin-arm64/bin/winter
+          chmod +x "$BIN"
+          test -x "$BIN"
+          file "$BIN" | grep -q "Mach-O 64-bit executable arm64" || { echo "restore: $BIN is not a Mach-O 64-bit arm64 executable" >&2; file "$BIN" >&2; exit 1; }
+          shasum -a 256 -c winter-darwin-arm64.sha256
 
       # --- the gates: the exact verification sequence ci.yml's `build` and `official-fixture-compile`
       # jobs already run on every push, repeated here so a tag pushed out of step with CI history (or
@@ -160,7 +231,10 @@ jobs:
   # job -- carries `id-token: write`. `contents: read` is repeated explicitly beside it; nothing here
   # needs `packages: write` (that is the other job's grant and stays there).
   publish-npm:
-    needs: publish
+    # P9a-4: keeps `needs: publish` (npm never runs until GitHub Packages succeeded) AND gains
+    # `needs: build-platform` (the darwin-arm64 binary this job's own npm publish ships must exist on
+    # the real artifact too -- this job checks out and downloads afresh, exactly like job 1).
+    needs: [publish, build-platform]
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -179,6 +253,18 @@ jobs:
           registry-url: "https://registry.npmjs.org"
           scope: "@yanlinglabs"
       - run: pnpm install
+      # P9a-4: same restore + verify as job 1 -- BEFORE this job's own gates or its publish step.
+      - uses: actions/download-artifact@v4
+        with: { name: winter-darwin-arm64 }
+      - name: "restore + verify the platform binary before anything downstream can publish it"
+        run: |
+          set -euo pipefail
+          tar -xf winter-darwin-arm64.tar -C packages/platform/darwin-arm64
+          BIN=packages/platform/darwin-arm64/bin/winter
+          chmod +x "$BIN"
+          test -x "$BIN"
+          file "$BIN" | grep -q "Mach-O 64-bit executable arm64" || { echo "restore: $BIN is not a Mach-O 64-bit arm64 executable" >&2; file "$BIN" >&2; exit 1; }
+          shasum -a 256 -c winter-darwin-arm64.sha256
       # The same two gates the GitHub Packages job ran, repeated here because this job checks out
       # afresh: the version/tag agreement, and the compiled emit the tarballs must contain.
       - run: bun run scripts/check-release-version.ts

RELEASING.md

@@ -29,15 +29,54 @@ pnpm strips `scripts` from the packed manifest, so the published package carries
 
 | Registry | Job | Packages | Credential |
 | --- | --- | --- | --- |
-| GitHub Packages | `publish` | all five | `secrets.GITHUB_TOKEN`, `packages: write` |
-| public npm | `publish-npm` | the closure of the wrapper + the two harness roots — all five today | `secrets.NPM_TOKEN`, `id-token: write` for provenance |
+| GitHub Packages | `publish` | all six | `secrets.GITHUB_TOKEN`, `packages: write` |
+| public npm | `publish-npm` | the closure of the wrapper + the two harness roots + the wrapper's `optionalDependency` — all six today | `secrets.NPM_TOKEN`, `id-token: write` for provenance |
 
 Neither registry is chosen on a command line. `--registry` sets only `registries.default`, and both
 pnpm and npm consult the **scope** binding first — a committed `@yanlinglabs:registry` line would
 therefore beat it, which is why the project `.npmrc` pins nothing. Each job binds its own scope *and*
 credential with `actions/setup-node` (`registry-url` + `scope`), and
 `scripts/publish-routing.test.ts` proves the routing with real `npm publish --dry-run` runs.
 
+## The darwin-arm64 platform package (P9a-3/P9a-4)
+
+`@yanlinglabs/winter-agent-sdk-darwin-arm64` ships the compiled `winter` runtime binary — the
+artifact the wrapper spawns — as an `optionalDependency` of `@yanlinglabs/winter-agent-sdk`. It is
+bin-only: no `main`, no `types`, no `exports` at all, just `bin: { winter: "bin/winter" }`, gated on
+`os: ["darwin"]` / `cpu: ["arm64"]` so a package manager that honours those fields (npm; `bun install`
+partially — see below) simply does not fetch it on any other platform.
+
+**Built ONLY on a macOS `arm64` runner.** `bun build --compile` targets the CURRENT host — it does not
+cross-compile — so a `build-platform` job (`runs-on: macos-15`) exists in BOTH workflows: `ci.yml`
+runs it on every push (no tag pin, and it runs the smoke's real EXECUTE path —
+`smoke-installed.ts --runtime=bun` actually spawns the just-built binary, since `os`/`cpu` match on
+that runner) so a broken darwin build fails long before a tag exists; `release.yml` runs the same
+build, additionally checks the binary's own `--version` against the pushed tag, tars it (GitHub
+Actions artifact uploads drop the executable bit, which is exactly why this matters), and uploads it
+as one artifact. Both jobs assert `uname -s`/`uname -m` themselves rather than trusting the `macos-15`
+label.
+
+**Both publish jobs `needs: build-platform`, download that ONE artifact, and restore + verify it —
+`chmod +x`, `test -x`, `file` reports `Mach-O 64-bit executable arm64`, `shasum -a 256 -c` against the
+recorded checksum — BEFORE their own version-tag gate and BEFORE the publish step.** Neither job
+rebuilds the binary itself: they ship exactly what `build-platform` produced.
+
+**Locally**, `bun run build:runtime --platform-package` (or `bun run scripts/build-runtime.ts
+--platform-package`) stages `packages/platform/darwin-arm64/bin/winter` — git-ignored, built on
+demand, never committed. `scripts/release-pack.ts` HARD-FAILS a pack attempted on a matching host
+(`darwin`/`arm64`) with that file missing, naming the exact command to run first; on a non-matching
+host (e.g. this repo's own `ubuntu-latest` `pack-smoke` jobs) the same absence is expected and
+tolerated — a package manager on Linux was never going to fetch this binary either.
+
+**The smoke (`scripts/smoke-installed.ts`) treats a bin-only package differently from an importable
+one**: it executes `<bin> --version` and compares it to the package's own `version` when `os`/`cpu`
+match the current host, and prints an explicit `SKIP … (bin-only; os/cpu mismatch on …)` line
+otherwise — never a silent no-op, and never an import attempt that would fail for the wrong reason.
+
+A Norma consumer (`packages/core`) resolves this package via `createRequire(...).resolve` and never
+needs `dist/winter` built from an SDK checkout once it installs from a real release —
+see that repo's `runtime-sdk/executable.ts` and P9a-8/P9a-9.
+
 The npm set is **data** (`winter.publish.npm` per manifest), asserted to equal the transitive
 workspace `dependencies` closure of the ROOTS: the wrapper, plus every package flagged
 `winter.publish.harness` (R-7b-5 — the two conformance harnesses, which the out-of-repo router
@@ -101,7 +140,7 @@ English, and a regex over English is a heuristic:
 Round 4 narrowed the negation skip to the matched clause and accepts unbackticked `src/`, which closes
 the two evasions the review demonstrated. The class remains: these gates catch the mistakes people
 actually make (a stale sentence surviving a rewrite) and cannot prove a README is true. **When you
-change what ships, re-read the five package READMEs** — the gate is a net, not a proof.
+change what ships, re-read the six package READMEs** — the gate is a net, not a proof.
 
 ## What ships