MrLPF · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026
diff --git a/.github/workflows/forge-rl-ci.yml b/.github/workflows/forge-rl-ci.yml
@@ -0,0 +1,191 @@
+name: ForgeRL CI
+
+on:
+  pull_request:
+    paths:
+      - "ForgeRL/**"
+      - ".github/workflows/forge-rl-ci.yml"
+  push:
+    branches: [master]
+    paths:
+      - "ForgeRL/**"
+      - ".github/workflows/forge-rl-ci.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  core:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: ForgeRL/pyproject.toml
+      - name: Install CPU dependencies
+        working-directory: ForgeRL
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e '.[dev]'
+      - name: Compile source tree
+        working-directory: ForgeRL
+        run: python -m compileall -q src tests scripts
+      - name: Core tests
+        working-directory: ForgeRL
+        run: pytest -q -m 'not distributed'
+      - name: Runtime microbenchmark
+        working-directory: ForgeRL
+        run: python scripts/benchmark_runtime.py --items 20000 --width 64 --slots 32
+      - name: M1 fast-mailbox inference microbenchmark
+        working-directory: ForgeRL
+        run: |
+          python scripts/benchmark_m1_inference.py \
+            --service-mode mailbox-fast \
+            --actors 2 --requests-per-actor 25 --items-per-request 4 \
+            --width 16 --max-batch-items 16 --min-batch-items 8
+      - name: M1 v1/v2 acceptance correctness smoke
+        if: matrix.python-version == '3.12'
+        working-directory: ForgeRL
+        env:
+          OMP_NUM_THREADS: "1"
+          MKL_NUM_THREADS: "1"
+        run: |
+          python scripts/benchmark_m1_acceptance.py \
+            --actors 2 --requests-per-actor 8 --items-per-request 2 \
+            --width 16 --output-size 4 --max-batch-items 8 \
+            --v2-min-batch-items 4 --legacy-min-batch-items 1 \
+            --max-wait-ms 0.5 --request-slots 4 --throughput-gate 0 \
+            --output benchmarks/results/m1-acceptance-smoke.json
+      - name: M1 mailbox tuning matrix smoke
+        if: matrix.python-version == '3.12'
+        working-directory: ForgeRL
+        env:
+          OMP_NUM_THREADS: "1"
+          MKL_NUM_THREADS: "1"
+        run: |
+          python scripts/benchmark_m1_tuning_matrix.py \
+            --preset smoke --repeats 1 --warmup-repeats 0 \
+            --requests-per-actor 8 \
+            --output benchmarks/results/m1-tuning-matrix-smoke.json
+      - name: M1 target-scale mailbox screening
+        if: matrix.python-version == '3.12'
+        working-directory: ForgeRL
+        env:
+          OMP_NUM_THREADS: "1"
+          MKL_NUM_THREADS: "1"
+        run: |
+          python scripts/benchmark_m1_acceptance.py \
+            --actors 8 --requests-per-actor 250 --items-per-request 8 \
+            --width 64 --output-size 4 --max-batch-items 128 \
+            --v2-min-batch-items 32 --legacy-min-batch-items 1 \
+            --max-wait-ms 0.5 --request-slots 8 --throughput-gate 0 \
+            --output benchmarks/results/m1-target-scale-screening.json
+      - name: M1 vector-batch sampling stability screening
+        if: matrix.python-version == '3.12'
+        working-directory: ForgeRL
+        env:
+          OMP_NUM_THREADS: "1"
+          MKL_NUM_THREADS: "1"
+          OPENBLAS_NUM_THREADS: "1"
+          NUMEXPR_NUM_THREADS: "1"
+        run: |
+          python scripts/benchmark_m1_double_buffer.py \
+            --actors 8 --requests-per-actor 1000 --items-per-request 8 \
+            --width 64 --output-size 4 --max-batch-items 128 \
+            --min-batch-items 64 --max-wait-ms 0.5 \
+            --v2-runtime vector-batch \
+            --repeats 3 --warmup-repeats 1 \
+            --output benchmarks/results/m1-double-buffer-screening.json
+      - name: Upload M1 acceptance smoke report
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: forgerl-m1-acceptance-smoke
+          path: ForgeRL/benchmarks/results/m1-acceptance-smoke.json
+          if-no-files-found: error
+      - name: Upload M1 tuning matrix smoke report
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: forgerl-m1-tuning-matrix-smoke
+          path: ForgeRL/benchmarks/results/m1-tuning-matrix-smoke.json
+          if-no-files-found: error
+      - name: Upload M1 target-scale screening report
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: forgerl-m1-target-scale-screening
+          path: ForgeRL/benchmarks/results/m1-target-scale-screening.json
+          if-no-files-found: error
+      - name: Upload M1 vector-batch screening report
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: forgerl-m1-vector-batch-screening
+          path: ForgeRL/benchmarks/results/m1-double-buffer-screening.json
+          if-no-files-found: error
+
+  distributed:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: ForgeRL/pyproject.toml
+      - name: Install CPU dependencies
+        working-directory: ForgeRL
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e '.[dev]'
+      - name: Two-process Gloo learner test
+        working-directory: ForgeRL
+        run: pytest -q -m distributed
+
+  gym-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: ForgeRL/pyproject.toml
+      - name: Install Gymnasium benchmark dependencies
+        working-directory: ForgeRL
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e '.[dev,gym]'
+      - name: CartPole environment smoke benchmark
+        working-directory: ForgeRL
+        run: python scripts/benchmark_env.py --env CartPole-v1 --envs 8 --steps 5000
+      - name: Pendulum environment smoke benchmark
+        working-directory: ForgeRL
+        run: python scripts/benchmark_env.py --env Pendulum-v1 --envs 8 --steps 5000
+      - name: M1 PPO learning plumbing smoke
+        working-directory: ForgeRL
+        env:
+          OMP_NUM_THREADS: "1"
+          MKL_NUM_THREADS: "1"
+        run: |
+          python scripts/benchmark_m1_learning.py \
+            --smoke --seeds 7 \
+            --environments CartPole-v1,Pendulum-v1 \
+            --device cpu \
+            --output benchmarks/results/m1-learning-smoke.json
+      - name: Upload M1 learning smoke report
+        uses: actions/upload-artifact@v4
+        with:
+          name: forgerl-m1-learning-smoke
+          path: ForgeRL/benchmarks/results/m1-learning-smoke.json
+          if-no-files-found: error
diff --git a/.github/workflows/forge-rl-gpu-smoke.yml b/.github/workflows/forge-rl-gpu-smoke.yml
@@ -0,0 +1,27 @@
+name: ForgeRL GPU learner smoke
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  torchrun:
+    runs-on: [self-hosted, linux, x64, gpu]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install ForgeRL
+        working-directory: ForgeRL
+        run: pip install -e '.[dev]'
+      - name: Run local multi-GPU learner group
+        working-directory: ForgeRL
+        env:
+          FORGE_RL_EXPECTED_GPUS: "2"
+        run: |
+          python - <<'PY'
+          import os, torch
+          expected = int(os.environ['FORGE_RL_EXPECTED_GPUS'])
+          assert torch.cuda.device_count() >= expected, (torch.cuda.device_count(), expected)
+          PY
+          torchrun --standalone --nproc-per-node=2 scripts/distributed_smoke.py
diff --git a/.github/workflows/forge-rl-m1-formal.yml b/.github/workflows/forge-rl-m1-formal.yml
@@ -0,0 +1,137 @@
+name: ForgeRL M1 formal acceptance
+
+on:
+  workflow_dispatch:
+    inputs:
+      device:
+        description: Pre-provisioned benchmark device
+        required: true
+        default: cpu
+        type: choice
+        options: [cpu, cuda]
+      seeds:
+        description: Exactly five or more comma-separated seeds
+        required: true
+        default: "1,2,3,4,5"
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  formal-m1:
+    runs-on: [self-hosted, linux, x64, forgerl-benchmark]
+    timeout-minutes: 720
+    env:
+      OMP_NUM_THREADS: "1"
+      MKL_NUM_THREADS: "1"
+      OPENBLAS_NUM_THREADS: "1"
+      NUMEXPR_NUM_THREADS: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify pinned benchmark image
+        working-directory: ForgeRL
+        run: |
+          command -v taskset >/dev/null || { echo "taskset is required" >&2; exit 2; }
+          test -n "${FORGERL_CPUSET:-}" || {
+            echo "FORGERL_CPUSET must identify the pinned benchmark cores" >&2
+            exit 2
+          }
+          python - <<'PY'
+          import os
+          import gymnasium
+          import numpy
+          import torch
+          expected_torch = os.environ.get("FORGERL_EXPECTED_TORCH")
+          expected_gym = os.environ.get("FORGERL_EXPECTED_GYMNASIUM")
+          if expected_torch and torch.__version__ != expected_torch:
+              raise SystemExit(f"torch {torch.__version__} != {expected_torch}")
+          if expected_gym and gymnasium.__version__ != expected_gym:
+              raise SystemExit(f"gymnasium {gymnasium.__version__} != {expected_gym}")
+          requested = "${{ inputs.device }}"
+          if requested == "cuda" and not torch.cuda.is_available():
+              raise SystemExit("CUDA formal acceptance requested but CUDA is unavailable")
+          print({
+              "python": __import__("sys").version.split()[0],
+              "torch": torch.__version__,
+              "numpy": numpy.__version__,
+              "gymnasium": gymnasium.__version__,
+              "cuda": torch.cuda.is_available(),
+              "cpuset": os.environ["FORGERL_CPUSET"],
+          })
+          PY
+          python -m pip install -e . --no-deps
+      - name: Run five-seed CartPole/Pendulum vector-batch learning gate
+        working-directory: ForgeRL
+        run: |
+          taskset -c "$FORGERL_CPUSET" \
+            python scripts/benchmark_m1_learning.py \
+              --seeds "${{ inputs.seeds }}" \
+              --environments CartPole-v1,Pendulum-v1 \
+              --device "${{ inputs.device }}" \
+              --require-learning-gate \
+              --output benchmarks/results/m1-learning-formal.json
+          python - <<'PY'
+          import json
+          from pathlib import Path
+          report = json.loads(Path("benchmarks/results/m1-learning-formal.json").read_text())
+          if report.get("status") != "GO" or not report.get("learning_gate_passed"):
+              raise SystemExit("formal learning gate did not pass")
+          runtimes = {
+              run.get("runtime_metrics", {}).get("runtime")
+              for run in report.get("runs", [])
+              if run.get("subject") == "v2"
+          }
+          if runtimes != {"vector-batch-learning"}:
+              raise SystemExit(f"formal v2 learning used unexpected runtimes: {runtimes}")
+          PY
+      - name: Run controlled vector-batch stability gate
+        working-directory: ForgeRL
+        run: |
+          taskset -c "$FORGERL_CPUSET" \
+            python scripts/benchmark_m1_double_buffer.py \
+              --actors 8 --requests-per-actor 2000 --items-per-request 8 \
+              --width 64 --output-size 4 --max-batch-items 128 \
+              --min-batch-items 64 --max-wait-ms 0.5 \
+              --v2-runtime vector-batch \
+              --repeats 3 --warmup-repeats 1 --controlled \
+              --output benchmarks/results/m1-vector-batch-controlled.json
+          python - <<'PY'
+          import json
+          from pathlib import Path
+          report = json.loads(Path("benchmarks/results/m1-vector-batch-controlled.json").read_text())
+          if report.get("status") != "DOUBLE_BUFFER_CANDIDATE":
+              raise SystemExit(f"vector-batch stability gate failed: {report.get('status')}")
+          if not report.get("formal_eligible") or not report.get("double_buffer_stable_two_x"):
+              raise SystemExit("vector-batch evidence is not formal and stable >=2x")
+          if not report.get("work_conservation", {}).get("identical"):
+              raise SystemExit("single/double-buffer work is not identical")
+          if not report.get("single_buffer", {}).get("correctness_passed"):
+              raise SystemExit("single-buffer correctness failed")
+          if not report.get("double_buffer", {}).get("correctness_passed"):
+              raise SystemExit("double-buffer correctness failed")
+          PY
+      - name: Run final vector-batch M1 gate
+        working-directory: ForgeRL
+        run: |
+          taskset -c "$FORGERL_CPUSET" \
+            python scripts/benchmark_m1_acceptance.py \
+              --actors 8 --requests-per-actor 2000 --items-per-request 8 \
+              --width 64 --max-batch-items 128 \
+              --v2-min-batch-items 64 --legacy-min-batch-items 1 \
+              --v2-runtime vector-batch \
+              --device "${{ inputs.device }}" \
+              --throughput-gate 2.0 \
+              --learning-report benchmarks/results/m1-learning-formal.json \
+              --require-go \
+              --output benchmarks/results/m1-final.json
+      - name: Upload formal M1 evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: forgerl-m1-formal-evidence
+          path: |
+            ForgeRL/benchmarks/results/m1-learning-formal.json
+            ForgeRL/benchmarks/results/m1-vector-batch-controlled.json
+            ForgeRL/benchmarks/results/m1-final.json
+          if-no-files-found: warn