chore(deps): bump the MLX pin and declare a base commit for each overlay

[inureyes]

Summary

Bumps the pinned upstream ml-explore/mlx commit in src/lib/mlx-cpp/CMakeLists.txt from 81ba1c6a0e50a9268b931579c2d4f1158b9aab5a to 59d600b5e64c238427d0f8d897ab7c682ef4d3d2 (14 upstream commits) and establishes a single machine-readable // Modified from upstream MLX <sha> <upstream/relative/path> base declaration across all 32 overlay files under src/lib/mlx-cpp/patches/ and src/lib/mlx-cpp/patches-cuda/.

Changes

• Phase 1 (Base declarations across all 32 overlays): Determined each overlay's true copy or rebase commit by diffing against upstream ml-explore/mlx history (resolving v0.31.1 to ce45c525, fixing qmm_sm80.cu where Patched by mlxcel. preceded Modified from upstream MLX, and recording the copy/rebase SHAs for the remaining files).
• Phase 2 (Rebase conflicting and drifted overlays onto 59d600b5e):
  • 3-way merged the four quantized overlays (patches/mlx/backend/cuda/device/qmm_naive.cuh, patches/mlx/backend/cuda/quantized/qmm/qmv.cu, patches/mlx/backend/cuda/quantized/quantized.cpp, patches/mlx/backend/metal/quantized.cpp) and the two patches-cuda/ overlays (fast.cpp, ops.cpp) touched between 81ba1c6a and 59d600b5e, preserving every documented mlxcel delta.
  • Confirmed that upstream dfe17bafb (Fix fp quantized matmul corruption when the quantized dim is not a multiple of 32 ml-explore/mlx#3912, fixing fp-quantized matmul corruption when the quantized dim is not a multiple of 32 in mlx/backend/metal/kernels/fp_quantized.h and mlx/backend/metal/kernels/quantized.h) is intact: neither header is overlaid in src/lib/mlx-cpp/patches/mlx/backend/metal/kernels/, and patches/mlx/backend/metal/quantized.cpp is 3-way merged onto 59d600b5e (incorporating 3eb822cac and d9add9d11) with only the three MLXCEL_QMV_WIDE hunks differing from 59d600b5e:mlx/backend/metal/quantized.cpp.
  • Refreshed patches/mlx/backend/cuda/reduce/{all_reduce,col_reduce,row_reduce}.cu from ce45c525 (v0.31.1) onto 59d600b5e (folding in upstream 66f58032d const_cast removal and 790be8aa8 64-bit all_reduce planning for large inputs) so the drift check reports 0 upstream commits across all 32 overlays.
• Phase 3 (Pin bump and ROCm overlay retarget):
  • Updated GIT_TAG in src/lib/mlx-cpp/CMakeLists.txt to 59d600b5e64c238427d0f8d897ab7c682ef4d3d2.
  • Retargeted src/lib/mlx-cpp/patches-rocm/ onto 59d600b5e64c238427d0f8d897ab7c682ef4d3d2 via scripts/mlxcelverse/rocm_overlay.py retarget, added the fast::GatedDeltaUpdate fallback and NO_GPU_MULTI stub in mlx/backend/rocm/primitives.cpp (documented in LOCAL_FIXES.md item 6), and regenerated CORE_RESIDUAL.diff.
• Phase 4 (CONTRIBUTING.md): Added the Reconciling CUDA, Metal, and CPU source overlays subsection under Bumping the MLX upstream pin documenting the base-declaration format, the drift-check loop, and the git merge-file 3-way merge procedure.

ROCm overlay

• Fork commit (UPSTREAM fork_commit): 759159089fc9b17b3e0f1053abebff538f341fa5 (unchanged)
• Retargeted MLX pin (UPSTREAM retargeted_to_mlx_pin): 81ba1c6a0e50a9268b931579c2d4f1053abebff5 -> 59d600b5e64c238427d0f8d897ab7c682ef4d3d2
• Core files merged cleanly by rocm_overlay.py retarget: mlx/fast.cpp, mlx/fast.h, mlx/fast_primitives.h, mlx/ops.cpp
• Backend fix recorded in LOCAL_FIXES.md item 6: fast::GatedDeltaUpdate::use_fallback and NO_GPU_MULTI(GatedDeltaUpdate) in mlx/backend/rocm/primitives.cpp

Verification

• bash scripts/ci/mlx_pinned_commit.sh prints 59d600b5e64c238427d0f8d897ab7c682ef4d3d2 and cargo test -p mlxcel-mlx-pin passes (27/27 tests).
• Overlay drift check across all 32 files under src/lib/mlx-cpp/patches/ and src/lib/mlx-cpp/patches-cuda/ against 59d600b5e64c238427d0f8d897ab7c682ef4d3d2 produces 0 NO BASE lines and 0 DRIFT lines.
• make verify-versions verify-kernel-dtype-keys verify-kernel-port-dispatch verify-llama-compat verify-rocm-overlay verify-python-tooling verify-fmt passes.
• Real quantized checkpoint validation (Qwen3-0.6B-4bit, greedy --temp 0, 32 tokens) on this AMD Ryzen AI MAX+ 395 (gfx1151) Linux host:
  • ROCm GPU (bash scripts/rocm_gpu_guard.sh -- bash scripts/ci/rocm_smoke.sh): 32 tokens generated at 251.24 tok/s, matching the pre-bump greedy output token-for-token (Okay, the user wants me to write a one-sentence about the ocean. Let me start by brainstorming some key elements of the ocean. The).
  • CPU stream (MLXCEL_DEVICE=cpu): identical 32-token greedy output.
• Cross-host note: the three Apple Silicon Metal turbo launcher tests (sparse_v_kernel_threshold_zero_matches_graph, delegated_fused_kernel_matches_reference_over_200_steps, delegated_steel_envelope_matches_cold_only_fused_over_200_steps) and the GB10 CUDA hardware suite were not run locally because this validation host is a Linux AMD gfx1151 ROCm machine without Metal or NVIDIA CUDA hardware (CI runs the GB10 CUDA gate).

Closes #1932

[inureyes]

Implementation Review Summary

Intent

Bump the pinned upstream MLX commit to 59d600b5e, establish machine-readable base declarations across all 32 overlays, 3-way rebase drifted overlays while preserving all custom kernels, and document the overlay lifecycle in CONTRIBUTING.md.

Findings Addressed

• Upstream MLX pin bumped to 59d600b5e64c238427d0f8d897ab7c682ef4d3d2 in CMakeLists.txt and verified with mlx_pinned_commit.sh and cargo test -p mlxcel-mlx-pin (LOW)
• Machine-readable // Modified from upstream MLX <sha> <path> headers declared across all 32 overlays in patches/ and patches-cuda/ with each SHA resolving in upstream MLX (LOW)
• All 9 conflicting or drifted overlays 3-way merged onto 59d600b5e with 0 drift commits and all mlxcel custom kernel deltas preserved (LOW)
• Upstream fix dfe17bafb (#3912) verified intact without regressions in fp-quantized matmul (LOW)
• ROCm overlay retargeted to 59d600b5e with GatedDeltaUpdate fallback and NO_GPU_MULTI stub, passing make verify-rocm-overlay (29/29 checks) (LOW)
• CONTRIBUTING.md updated with CUDA/Metal/CPU overlay base conventions and 3-way merge procedure (LOW)
• Bilingual technical reports written for PR chore(deps): bump the MLX pin and declare a base commit for each overlay #2298 (LOW)

Remaining Items

• None

Verification

• All stated requirements implemented
• No placeholder/mock code remaining
• Integrated into project code flow
• Project conventions followed
• Existing modules reused where applicable
• No unintended structural changes
• Tests pass

[inureyes]

Security & Performance Review Summary

Findings: 0 Critical, 0 High, 0 Medium, 0 Low.

Security Analysis

• Memory Safety & Bounds: CUDA reduction overlays incorporate upstream 64-bit planning (size_t and cuda::ceil_div), preventing integer overflow on tensor reductions over 2 billion elements. Input index access for global_scale in GatherQMM::eval_gpu is safely guarded by inputs.size() == 6.
• Bug Fix Retention: Upstream fix dfe17bafb (#3912, preventing memory corruption when the quantized dimension is not a multiple of 32 in mlx/backend/metal/kernels/{fp_quantized,quantized}.h) is preserved intact without overlay interference.
• Injection & Exposure: No external commands, secrets, or unchecked paths introduced.

Performance Analysis

• Kernel Efficiency & Portability: All 32 CUDA, Metal, and CPU overlays declared with machine-readable base SHAs and 3-way merged against pin 59d600b5e with zero drift. Custom performance paths (MLXCEL_QMV_WIDE runtime off-switch, multirow qmv weight reuse, Volta SM70 MmaPath parameterization) are fully preserved.
• ROCm Compatibility: Upstream primitive fast::GatedDeltaUpdate cleanly routes to graph fallback on ROCm (use_fallback = true and NO_GPU_MULTI stub), preventing execution stalls or undefined symbol link failures.
• Hardware Verification: AMD gfx1151 ROCm GPU smoke decode yielded 251.24 tok/s with token-for-token greedy output parity against CPU reference.

Contract Gates Passed

• bash scripts/ci/mlx_pinned_commit.sh matches src/lib/mlx-cpp/CMakeLists.txt (59d600b5e64c238427d0f8d897ab7c682ef4d3d2).
• cargo test -p mlxcel-mlx-pin passed (27/27 tests).
• make verify-rocm-overlay passed (29 checks).
• make verify-versions verify-kernel-dtype-keys verify-kernel-port-dispatch verify-llama-compat verify-python-tooling verify-fmt passed.
• Overlay drift check across all 32 overlays reported 0 NO BASE and 0 DRIFT.

[inureyes]

PR Finalization Complete

Summary

• Tests: Verified cargo test -p mlxcel-mlx-pin (27/27 tests), bash scripts/ci/mlx_pinned_commit.sh, make verify-rocm-overlay (29 checks), and repository gates make verify-versions verify-kernel-dtype-keys verify-kernel-port-dispatch verify-llama-compat verify-python-tooling verify-fmt (123 Python tooling tests passed).
• Documentation: Verified CONTRIBUTING.md overlay reconciliation guide, validated and committed bilingual technical reports (TECHNICAL_REPORTS/2298-bump-mlx-pin-overlay-bases-20261014.{en,ko}.md) in commit a8ae53f, and pushed to origin.
• Code Quality & Drift: 0 NO BASE and 0 DRIFT lines across all 32 overlays against MLX pin 59d600b5e64c238427d0f8d897ab7c682ef4d3d2. Format check (make verify-fmt) and git diff --check clean.

All checks passing. Ready for merge.