Skip to content

chore: bump vendored MLX to upstream main 2026-06-11 and retire the steel GEMM overlay#223

Merged
inureyes merged 2 commits into
mainfrom
chore/issue-222-mlx-bump
Jun 11, 2026
Merged

chore: bump vendored MLX to upstream main 2026-06-11 and retire the steel GEMM overlay#223
inureyes merged 2 commits into
mainfrom
chore/issue-222-mlx-bump

Conversation

@inureyes

Copy link
Copy Markdown
Member

Summary

Bumps the vendored MLX pin from 8496122 (upstream main, 2026-05-09) to a6ec7123dac814417147e21d4aeed694924ddd4d (upstream main, 2026-06-11) and retires the steel GEMM mma.h overlay that issue #217 introduced: the new pin carries the upstream safe-load fix (ml-explore/mlx PRs #3560/#3565) natively, so keeping the whole-file overlay would have silently reverted upstream changes to that file at the next touch.

Closes #222

What changed

  • src/lib/mlx-cpp/CMakeLists.txt: GIT_TAG moved to a6ec712; the mma.h overlay file and its _metal_patch_files entry are removed (a short comment records the retirement).
  • src/lib/mlxcel-core/build.rs: MLX_EXPECTED_COMMIT moved in lock-step (the marker-file mechanism purged the stale _deps cache and rebuilt MLX from the new commit on the first build).
  • The two remaining overlays (compiled.cpp mixed-dtype static_cast, kernels/utils.h simdgroup-matrix include + metal::vec qualification) were diffed against the new pin: upstream did not modify either file in the 2026-05-09 to 2026-06-11 window, so both apply unchanged and no re-derivation was needed.
  • No bridge (mlx_cxx_bridge.cpp) or turbo-kernel changes were required: the month of upstream API drift did not touch any surface mlxcel uses, and the full build compiled clean on the first attempt.

Upstream fixes picked up by the new pin

steel GEMM safe-load (#3560/#3565, previously overlaid), qvm_split_k batch stride (#3497), rope single-token multiple-sequences (#3498), int32 shape-product overflow detection (#3524), int32 overflow in matvec row offset and gather-MM batch stride (#3609), metallib deployment-target link flag (#3501), compile-cache and tracing-state thread-safety (#3628/#3638), scatter_prod NaN hang (#3492).

Verification (M1 Ultra, real models)

  • Kernel regression tests added for exactly this class of change: steel_gemm_edge_tile_safe_load_matches_reference green on the native upstream fix (overlay gone), DiffusionGemma real_model_forward_determinism (buffer-cache-warmed byte-determinism of encoder and canvas forwards) green.
  • DiffusionGemma temperature-0 deterministic CLI run is BYTE-IDENTICAL across the bump (commit-stream md5 c38559cc..., the same value as on the old pin with the overlay), and the 256-token essay run reproduces the identical 34-step trajectory at 631 ms/step (pre-bump 634 ms).
  • Paged scheduler parity 4/4 and prefix-share parity 2/2 (qwen3 + llama3, byte-identical decode vs dense reference, --test-threads=1).
  • Full serial lib suite: 3150 passed / 0 failed. Cold clippy clean on both CI feature sets (metal,accelerate and +test-utils).
  • Throughput sanity vs pre-bump baselines: qwen2.5-0.5b decode 321.8 tok/s (>= baseline), gemma-4-26b-a4b decode 69.5 tok/s (baseline 68-71), DiffusionGemma per-step 631 ms (baseline 634 ms).
  • Live mlxcel-server smoke with the DiffusionGemma worker on the new pin: chat completion answers correctly with finish_reason stop.

Updates GIT_TAG and MLX_EXPECTED_COMMIT in lock-step and retires the steel
GEMM mma.h overlay: the new pin carries the upstream safe-load fix
(ml-explore/mlx PRs #3560/#3565) natively. The remaining two overlays
(compiled.cpp mixed-dtype casts, kernels/utils.h simdgroup-matrix include)
were diffed against the new pin: upstream did not touch either file in the
2026-05-09 to 2026-06-11 window, so both apply unchanged.

Part of #222
@inureyes inureyes added status:review Under review type:enhancement New features, capabilities, or significant additions priority:high High priority area:core mlxcel-core: MLX FFI, primitives, KV cache, layers labels Jun 11, 2026
The pin bump in PR #223 moved GIT_TAG and MLX_EXPECTED_COMMIT to a6ec712 but missed the third location: the release workflow's MLX build-cache validator still pinned the old 84961223, so it would purge a valid a6ec712 _deps cache on every release run (the comment there already states it must match the other two).

Also refreshes comments left stale by the mma.h overlay retirement: the two steel GEMM safe-load regression tests now describe the fix as native upstream (carried by the pin) rather than pointing at the deleted overlay file, and the two CUDA quantized patch headers update their sync anchor to a6ec712 (upstream did not touch those files between 84961223 and a6ec712, so the patches still match the new pin). The #3443 (c9aa5605..84961223) range stays as the historical landing record.

Part of #222
@inureyes

Copy link
Copy Markdown
Member Author

Implementation Review Summary

Intent

Bump the vendored MLX pin from 8496122 to a6ec712 (2026-06-11) and retire the steel GEMM mma.h overlay now that the safe-load fix is native upstream.

Findings Addressed

  • .github/workflows/release.yml still pinned the OLD commit 84961223 as the build-cache validator's MLX_EXPECTED_COMMIT, despite an inline comment requiring it to match CMakeLists/build.rs. This is the documented third pin location ("three-location pin update"). Left stale, the release workflow would purge a valid a6ec712 _deps cache on every release run. Bumped to a6ec712. (HIGH)
  • Two steel GEMM regression tests (ffi_tests.rs::steel_gemm_edge_tile_safe_load_matches_reference, diffusion_gemma/tests.rs::real_model_forward_determinism) had doc comments pointing at the now-deleted overlay path and calling it "the overlay." Reworded to describe the fix as native upstream (carried by the pin); tests are unchanged and remain meaningful. (LOW)
  • Two CUDA quantized patch headers (quantized.cpp, qmm/qmm.h) carried a "matches/Synced to upstream 84961223" sync anchor. Verified via upstream history that those files were not modified between 84961223 (2026-05-05 last touch) and a6ec712, so the patches still apply; updated the anchor to a6ec712. The #3443 (c9aa5605..84961223) historical PR-range record was preserved. (LOW)

Remaining Items

  • None.

Verification

  • Both pinned hashes match exactly (a6ec7123dac814417147e21d4aeed694924ddd4d in CMakeLists GIT_TAG and build.rs MLX_EXPECTED_COMMIT) and reference a real upstream commit (2026-06-11).
  • No leftover live references to the old pin or the retired overlay; remaining 84961223 occurrences are historical (CHANGELOG, benchmark provenance, the #3443 PR-range anchor).
  • Remaining _metal_patch_files (compiled.cpp, utils.h) both exist in patches/.
  • steel_gemm_edge_tile_safe_load_matches_reference exists and is meaningful: it runs a non-tile-aligned fp32 GEMM against a composite reference, guarding the now-native fix.
  • No stray files: PR is exactly the two pin edits plus the overlay deletion (plus this review's comment/pin sync follow-up).

Note: builds were not re-run per the orchestrator's instruction; the orchestrator's real-model verification (DiffusionGemma byte-identical, paged parity, 3150/0 serial suite, cold clippy) stands.

@inureyes inureyes added status:done Completed and removed status:review Under review labels Jun 11, 2026
@inureyes
inureyes merged commit 0ebd984 into main Jun 11, 2026
5 checks passed
@inureyes
inureyes deleted the chore/issue-222-mlx-bump branch June 11, 2026 16:38
@inureyes inureyes added this to the 0.2 milestone Jun 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:core mlxcel-core: MLX FFI, primitives, KV cache, layers priority:high High priority status:done Completed type:enhancement New features, capabilities, or significant additions

Projects

None yet

Development

Successfully merging this pull request may close these issues.

chore: bump vendored MLX to upstream main (2026-06-11) and retire the steel GEMM overlay

1 participant