Fix macOS stock-level audio exhaustion

.github/workflows/commit-validation.yml

@@ -1086,11 +1086,11 @@ jobs:
         include:
           - bridge_label: OpenGL
             macos_graphics_bridge: opengl
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
             artifact_suffix: opengl
           - bridge_label: Metal
             macos_graphics_bridge: metal
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
             artifact_suffix: metal
 
     steps:
@@ -1121,6 +1121,18 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install meson ninja
 
+      - name: Prepare pinned OpenAL Soft
+        shell: bash
+        run: |
+          set -euo pipefail
+          prepared_root="${GITHUB_WORKSPACE}/.tmp/openal-soft-macos-arm64"
+          bash tools/build/prepare_macos_openal_soft.sh \
+            --architecture arm64 \
+            --deployment-target "${MACOSX_DEPLOYMENT_TARGET}" \
+            --output-root "${prepared_root}" \
+            --stage-install-dir .install
+          echo "PKG_CONFIG_PATH=${prepared_root}/lib/pkgconfig" >> "${GITHUB_ENV}"
+
       - name: Run selected validation profile
         shell: bash
         run: |
@@ -1210,11 +1222,11 @@ jobs:
         include:
           - bridge_label: OpenGL
             macos_graphics_bridge: opengl
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
             artifact_suffix: opengl
           - bridge_label: Metal
             macos_graphics_bridge: metal
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
             artifact_suffix: metal
 
     steps:
@@ -1254,6 +1266,18 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install meson ninja
 
+      - name: Prepare pinned OpenAL Soft
+        shell: bash
+        run: |
+          set -euo pipefail
+          prepared_root="${GITHUB_WORKSPACE}/.tmp/openal-soft-macos-x64"
+          bash tools/build/prepare_macos_openal_soft.sh \
+            --architecture x64 \
+            --deployment-target "${MACOSX_DEPLOYMENT_TARGET}" \
+            --output-root "${prepared_root}" \
+            --stage-install-dir .install
+          echo "PKG_CONFIG_PATH=${prepared_root}/lib/pkgconfig" >> "${GITHUB_ENV}"
+
       - name: Run selected validation profile
         shell: bash
         run: |

.github/workflows/macos-debug.yml

@@ -88,6 +88,19 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install meson ninja
 
+      - name: Prepare pinned OpenAL Soft
+        if: steps.select.outputs.selected == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          prepared_root="${GITHUB_WORKSPACE}/.tmp/openal-soft-macos-arm64"
+          bash tools/build/prepare_macos_openal_soft.sh \
+            --architecture arm64 \
+            --deployment-target 11.0 \
+            --output-root "${prepared_root}" \
+            --stage-install-dir .install
+          echo "PKG_CONFIG_PATH=${prepared_root}/lib/pkgconfig" >> "${GITHUB_ENV}"
+
       - name: Host diagnostics
         if: steps.select.outputs.selected == 'true'
         shell: bash
@@ -192,7 +205,8 @@ jobs:
             --wrap-mode=forcefallback \
             -Dplatform_backend=sdl3 \
             -Dbuild_renderer_vk=true \
-            -Dmacos_graphics_bridge=${{ matrix.bridge }}
+            -Dmacos_graphics_bridge=${{ matrix.bridge }} \
+            -Dmacos_openal_provider=system
 
       - name: Compile
         if: steps.select.outputs.selected == 'true'
@@ -269,11 +283,10 @@ jobs:
           retention-days: ${{ fromJSON(inputs.retention_days) }}
           include-hidden-files: true
 
-  # Migration-corridor compile check: builds against Homebrew OpenAL Soft with
-  # -Dmacos_openal_provider=system. This is migration testing only, not release
-  # evidence; release packages stay on apple_framework. No packaging or signoff.
+  # Compatibility-only compile check for Apple's deprecated framework. Release,
+  # package, and standard validation paths use pinned OpenAL Soft instead.
   macos-openal-migration:
-    name: macOS OpenAL Soft Migration Corridor (compile only)
+    name: macOS Apple OpenAL Compatibility Corridor (compile only)
     runs-on: macos-15
     timeout-minutes: 90
     env:
@@ -303,14 +316,7 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install meson ninja
 
-      - name: Install OpenAL Soft
-        shell: bash
-        run: |
-          set -euo pipefail
-          brew install openal-soft
-          echo "PKG_CONFIG_PATH=$(brew --prefix openal-soft)/lib/pkgconfig" >> "${GITHUB_ENV}"
-
-      - name: Configure (system OpenAL)
+      - name: Configure (Apple framework)
         shell: bash
         env:
           MACOSX_DEPLOYMENT_TARGET: "11.0"
@@ -322,9 +328,9 @@ jobs:
             --wrap-mode=forcefallback \
             -Dplatform_backend=sdl3 \
             -Dmacos_graphics_bridge=opengl \
-            -Dmacos_openal_provider=system
+            -Dmacos_openal_provider=apple_framework
 
-      - name: Compile (system OpenAL)
+      - name: Compile (Apple framework)
         shell: bash
         env:
           MACOSX_DEPLOYMENT_TARGET: "11.0"

.github/workflows/macos-sanitizer.yml

@@ -97,6 +97,19 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install meson ninja
 
+      - name: Prepare pinned OpenAL Soft
+        if: steps.select.outputs.selected == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          prepared_root="${GITHUB_WORKSPACE}/.tmp/openal-soft-macos-arm64"
+          bash tools/build/prepare_macos_openal_soft.sh \
+            --architecture arm64 \
+            --deployment-target "${MACOSX_DEPLOYMENT_TARGET}" \
+            --output-root "${prepared_root}" \
+            --stage-install-dir .install
+          echo "PKG_CONFIG_PATH=${prepared_root}/lib/pkgconfig" >> "${GITHUB_ENV}"
+
       - name: Record host diagnostics
         if: steps.select.outputs.selected == 'true'
         shell: bash
@@ -132,7 +145,7 @@ jobs:
             --wrap-mode=forcefallback \
             -Dplatform_backend=sdl3 \
             -Dmacos_graphics_bridge=${{ matrix.bridge }} \
-            -Dmacos_openal_provider=apple_framework \
+            -Dmacos_openal_provider=system \
             -Duse_pch=false \
             -Didlib_asserts=true \
             -Db_sanitize=address,undefined

.github/workflows/macos-universal2-candidate.yml

@@ -221,6 +221,18 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install meson ninja markdown
 
+      - name: Prepare pinned OpenAL Soft
+        shell: bash
+        run: |
+          set -euo pipefail
+          prepared_root="${GITHUB_WORKSPACE}/.tmp/openal-soft-macos-${{ matrix.binary_arch }}"
+          bash tools/build/prepare_macos_openal_soft.sh \
+            --architecture "${{ matrix.binary_arch }}" \
+            --deployment-target "${MACOSX_DEPLOYMENT_TARGET}" \
+            --output-root "${prepared_root}" \
+            --stage-install-dir .install
+          echo "PKG_CONFIG_PATH=${prepared_root}/lib/pkgconfig" >> "${GITHUB_ENV}"
+
       - name: Build and stage thin macOS runtime
         shell: bash
         run: |
@@ -236,7 +248,7 @@ jobs:
             --wrap-mode=forcefallback \
             -Dplatform_backend=sdl3 \
             -Dmacos_graphics_bridge=${{ matrix.bridge }} \
-            -Dmacos_openal_provider=apple_framework \
+            -Dmacos_openal_provider=system \
             -Dversion_track=stable \
             -Dversion_base_override=${{ needs.metadata.outputs.version }}
           bash tools/build/meson_setup.sh compile -C builddir
@@ -285,7 +297,7 @@ jobs:
             --source-manifest .tmp/gamelibs_stage/openq4_gamelibs_stage_manifest.json \
             --arch "${{ matrix.binary_arch }}" \
             --graphics-bridge "${{ matrix.bridge }}" \
-            --openal-provider apple_framework \
+            --openal-provider system \
             --deployment-target "${MACOSX_DEPLOYMENT_TARGET}" \
             --build-type debugoptimized
 

.github/workflows/manual-release.yml

@@ -549,7 +549,7 @@ jobs:
                       "binary_arch": "arm64",
                       "platform_backend": "sdl3",
                       "macos_graphics_bridge": "opengl",
-                      "macos_openal_provider": "apple_framework",
+                      "macos_openal_provider": "system",
                       "macos_release_mode": macos_release_mode,
                       "package_suffix": f"-opengl{macos_unsigned_suffix}",
                       "archive_format": macos_archive_format,
@@ -562,7 +562,7 @@ jobs:
                       "binary_arch": "arm64",
                       "platform_backend": "sdl3",
                       "macos_graphics_bridge": "metal",
-                      "macos_openal_provider": "apple_framework",
+                      "macos_openal_provider": "system",
                       "macos_release_mode": macos_release_mode,
                       "package_suffix": f"-metal{macos_unsigned_suffix}",
                       "archive_format": macos_archive_format,
@@ -748,12 +748,18 @@ jobs:
             sleep 10
           done
 
-      - name: Install macOS native dependencies
+      - name: Install macOS native dependencies and prepare pinned OpenAL Soft
         if: matrix.platform == 'macos'
         shell: bash
         run: |
           set -euo pipefail
-          echo "Using bundled Meson fallbacks for macOS third-party libraries."
+          prepared_root="${GITHUB_WORKSPACE}/.tmp/openal-soft-macos-${{ matrix.binary_arch }}"
+          bash tools/build/prepare_macos_openal_soft.sh \
+            --architecture "${{ matrix.binary_arch }}" \
+            --deployment-target 11.0 \
+            --output-root "${prepared_root}"
+          echo "OPENQ4_MACOS_OPENAL_ROOT=${prepared_root}" >> "${GITHUB_ENV}"
+          echo "PKG_CONFIG_PATH=${prepared_root}/lib/pkgconfig" >> "${GITHUB_ENV}"
 
       - name: Prepare OpenAL Soft (Windows)
         if: matrix.platform == 'windows'
@@ -841,6 +847,14 @@ jobs:
           bash tools/build/meson_setup.sh "${setup_args[@]}"
           bash tools/build/meson_setup.sh compile -C builddir
           bash tools/build/meson_setup.sh install -C builddir --no-rebuild --skip-subprojects
+          if [ "${{ matrix.platform }}" = "macos" ]; then
+            bash tools/build/prepare_macos_openal_soft.sh \
+              --verify-only \
+              --architecture "${{ matrix.binary_arch }}" \
+              --deployment-target 11.0 \
+              --output-root "${OPENQ4_MACOS_OPENAL_ROOT}" \
+              --stage-install-dir .install
+          fi
 
       - name: Verify checked-out and staged source provenance
         shell: bash

.github/workflows/push-verification.yml

@@ -423,25 +423,25 @@ jobs:
             artifact_name: macos-opengl
             runtime_smoke: true
             macos_graphics_bridge: opengl
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
           - name: macOS Metal Push Verification
             os: macos-15
             artifact_name: macos-metal
             runtime_smoke: true
             macos_graphics_bridge: metal
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
           - name: macOS Intel x64 OpenGL Push Verification
             os: macos-15-intel
             artifact_name: macos-x64-opengl
             runtime_smoke: true
             macos_graphics_bridge: opengl
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
           - name: macOS Intel x64 Metal Push Verification
             os: macos-15-intel
             artifact_name: macos-x64-metal
             runtime_smoke: true
             macos_graphics_bridge: metal
-            macos_openal_provider: apple_framework
+            macos_openal_provider: system
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -467,6 +467,23 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install meson ninja
 
+      - name: Prepare pinned OpenAL Soft (macOS)
+        if: startsWith(matrix.os, 'macos-')
+        shell: bash
+        run: |
+          set -euo pipefail
+          architecture=arm64
+          if [[ "${{ matrix.os }}" == "macos-15-intel" ]]; then
+            architecture=x64
+          fi
+          prepared_root="${GITHUB_WORKSPACE}/.tmp/openal-soft-macos-${architecture}"
+          bash tools/build/prepare_macos_openal_soft.sh \
+            --architecture "${architecture}" \
+            --deployment-target 11.0 \
+            --output-root "${prepared_root}" \
+            --stage-install-dir .install
+          echo "PKG_CONFIG_PATH=${prepared_root}/lib/pkgconfig" >> "${GITHUB_ENV}"
+
       - name: Install Linux native dependencies
         if: startsWith(matrix.os, 'ubuntu-')
         shell: bash