feat(moe): parallel execution prefetch queue for SSD expert streaming

.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-test:
+    name: Build and Test (macOS 15)
+    runs-on: macos-15
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Metal Toolchain
+        run: xcodebuild -downloadComponent MetalToolchain || true
+
+      - name: Cache Swift packages
+        uses: actions/cache@v4
+        with:
+          path: .build
+          key: ${{ runner.os }}-spm-v1-${{ hashFiles('Package.resolved') }}
+          restore-keys: |
+            ${{ runner.os }}-spm-v1-
+
+      - name: Clear stale module cache
+        run: find .build -type d -name ModuleCache -exec rm -rf {} + 2>/dev/null || true
+
+      - name: Resolve dependencies
+        run: swift package resolve
+
+      - name: Build (Release)
+        run: swift build -c release -Xswiftc -enable-testing --build-tests
+
+      - name: Install MLX Metal library
+        run: |
+          python3 -m venv /tmp/mlx_venv
+          /tmp/mlx_venv/bin/pip install --quiet mlx
+          MLX_LIB=$(find /tmp/mlx_venv -name "mlx.metallib" | head -n 1)
+          # Copy to build root and release root
+          cp $MLX_LIB .build/release/ 2>/dev/null || true
+          cp $MLX_LIB ./ 2>/dev/null || true
+          # Find the xctest bundle's MacOS directory and put it right next to the test runner binary
+          find .build -type d -name "MacOS" -exec cp $MLX_LIB {}/ \; 2>/dev/null || true
+          # Also put it in Resources just in case
+          find .build -type d -name "Resources" -exec cp $MLX_LIB {}/ \; 2>/dev/null || true
+          # Aggressive: put it next to any executable in the release dir
+          find .build -type f -executable -exec cp $MLX_LIB $(dirname "{}")/ \; 2>/dev/null || true
+
+      - name: Run Library Tests (Metal Accelerated)
+        run: swift test -c release --skip-build
+
+      - name: Gemma 4 PLE Stabilization Gate
+        run: |
+          # Verify PLE signal stability with full kernel support
+          swift test -c release --filter Gemma4StabilizationTests --skip-build
+
+      - name: Speculative Decoding Protection Gate
+        run: |
+          # Ensure speculative decoding parity and cache integrity are never regressed
+          swift test -c release --filter SpeculativeDecodingTests --skip-build
+
+      - name: High-Rigor Architectural Parity (Gemma 4)
+        run: |
+          # Verify Gemma 4 Gated Residuals and PLE math integrity
+          swift test -c release --filter Gemma4Tests --skip-build
+
+      - name: Performance & Memory Ceiling Audit (8GB Target)
+        run: |
+          # Enforce 6GB RSS limit and throughput baselines
+          swift test -c release --filter PerformanceRegressionTests --skip-build
+
+      - name: Upload test results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: library-test-results
+          path: .build/artifacts/
+          retention-days: 7

.github/workflows/performance_audit.yml

@@ -0,0 +1,28 @@
+name: Performance Audit
+
+on:
+  pull_request:
+    types: [labeled]
+
+jobs:
+  benchmark:
+    if: contains(github.event.pull_request.labels.*.name, 'run-benchmark')
+    name: Regression Benchmark
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build Benchmark Tool
+        run: swift build -c release --product BenchmarkHelpers
+
+      - name: Run Baseline Gemma4 Benchmark
+        run: |
+          # Use synthetic weights for performance tracking to avoid GBytes of downloads in CI
+          swift run -c release mlx-swift-lm-benchmark --model gemma4 --synthetic --prompt-len 512 --gen-len 128
+
+      - name: Run Memory Efficiency Audit
+        run: |
+          # Check for memory leaks / peak memory stability
+          swift run -c release mlx-swift-lm-benchmark --model gemma4 --synthetic --max-mem 4GB

.github/workflows/pull_request.yml

@@ -69,6 +69,18 @@ jobs:
         run: |
           pre-commit run --all || (echo "Style checks failed, please install pre-commit and run pre-commit run --all and push the change"; echo ""; git --no-pager diff; exit 1)
 
+  docs:
+    needs: lint
+    if: github.repository == 'ml-explore/mlx-swift-lm'
+    runs-on: [self-hosted, macos]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Verify documentation
+        run: scripts/verify-docs.sh
+
   mac_build_and_test:
     needs: lint
     if: github.repository == 'ml-explore/mlx-swift-lm'

.github/workflows/regression_harness.yml

@@ -0,0 +1,42 @@
+name: Regression Harness
+
+on:
+  pull_request:
+    types: [labeled]
+
+jobs:
+  performance-audit:
+    if: contains(github.event.pull_request.labels.*.name, 'run-benchmark')
+    name: Performance & Memory Audit
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Metal Toolchain
+        run: xcodebuild -downloadComponent MetalToolchain || true
+
+      - name: Build Benchmark Tool
+        run: swift build -c release --product BenchmarkHelpers
+
+      - name: Install MLX Metal library
+        run: |
+          python3 -m venv /tmp/mlx_venv
+          /tmp/mlx_venv/bin/pip install --quiet mlx
+          cp /tmp/mlx_venv/lib/python*/site-packages/mlx/lib/mlx.metallib .build/release/
+
+      - name: TFLOPS Regression Check
+        run: |
+          # Verify that throughput remains stable
+          swift run -c release mlx-swift-lm-benchmark --model gemma4 --synthetic --prompt-len 512 --gen-len 128
+
+      - name: Memory Efficiency Audit
+        run: |
+          # Check peak memory stability (mimicking root project's speculative-decoding-eval)
+          swift run -c release mlx-swift-lm-benchmark --model gemma4 --synthetic --max-mem 4GB
+
+      - name: Token Variance Check
+        run: |
+          # Verify that the output token variance is within baseline (PLE stability)
+          swift run -c release mlx-swift-lm-benchmark --model gemma4 --synthetic --verbose

CONTRIBUTING.md

@@ -14,11 +14,44 @@ possible.
    You can also run the formatters manually as follows:
 
      ```
-     swift-format format --in-place --recursive Libraries Tools Applications
+     swift-format format --in-place --recursive Libraries Tools Applications IntegrationTesting
      ```
 
    or run `pre-commit run --all-files` to check all files in the repo.
 
+## Running Tests
+
+Unit tests run without any special hardware and do not download models.
+Note: `swift test` [does not work yet](https://github.com/ml-explore/mlx-swift?tab=readme-ov-file#xcodebuild) — use `xcodebuild` instead:
+
+```bash
+xcodebuild test -scheme mlx-swift-lm-Package -destination 'platform=macOS'
+```
+
+Integration tests verify end-to-end model loading and generation. They require
+macOS with Metal and download models from Hugging Face Hub on first run. These
+tests do not run in CI.
+
+Open `IntegrationTesting/IntegrationTesting.xcodeproj` in Xcode and run the
+test target (`Cmd+U` or via the Test Navigator), or use `xcodebuild`:
+
+```bash
+# Run all integration tests
+xcodebuild test \
+  -project IntegrationTesting/IntegrationTesting.xcodeproj \
+  -scheme IntegrationTesting \
+  -destination 'platform=macOS'
+
+# Run a single test
+xcodebuild test \
+  -project IntegrationTesting/IntegrationTesting.xcodeproj \
+  -scheme IntegrationTesting \
+  -destination 'platform=macOS' \
+  -only-testing:IntegrationTestingTests/ToolCallIntegrationTests/qwen35FormatAutoDetection\(\)
+```
+
+See [Libraries/IntegrationTestHelpers/README.md](Libraries/IntegrationTestHelpers/README.md) for more details.
+
 ## Issues
 
 We use GitHub issues to track public bugs. Please ensure your description is