fix(build): isolate AEC source writes and preserve binding consistency

.github/workflows/python-linux.yml

@@ -131,8 +131,13 @@ jobs:
             echo "No pkg-config-visible system Abseil"
           fi
 
-      - name: Install locked environment (T1 + T2 voice)
-        run: uv sync --locked --extra voice --extra dev
+      - name: Qualify cold locked Voice install and standalone AEC wheel
+        # Builds an sdist/wheel as well as the locked install, verifies actual
+        # Meson resolution, and detects ignored build/install source pollution.
+        env:
+          # Regression: the qualifier must prevent an inherited uv log filter.
+          RUST_LOG: warn
+        run: python tools/verify_aec_source_build.py
 
       - name: Verify environment (voice profile)
         run: uv run --locked --no-sync python tools/verify_python_environment.py --profile voice
@@ -147,25 +152,6 @@ jobs:
           for n in ('torch', 'torchaudio', 'silero_vad', 'onnxruntime'));
           print('AEC 1.0.1 import and model-free Voice: PASS')"
 
-      - name: Assert bundled Abseil build
-        shell: bash
-        run: |
-          uv run --locked --no-sync python - <<'PYTHON'
-          import json
-          from pathlib import Path
-
-          info = Path("vendor/aec-audio-processing/webrtc-audio-processing/build/meson-info")
-          options = {
-              item["name"]: item["value"]
-              for item in json.loads((info / "intro-buildoptions.json").read_text())
-          }
-          assert "abseil-cpp" in options["force_fallback_for"], options["force_fallback_for"]
-          project = json.loads((info / "intro-projectinfo.json").read_text())
-          subprojects = {item["name"]: item["version"] for item in project["subprojects"]}
-          assert subprojects.get("abseil-cpp") == "20240722.0", subprojects
-          print("AEC build: forced bundled Abseil 20240722.0")
-          PYTHON
-
       - name: Check third-party provenance
         run: uv run --locked --no-sync python tools/check_third_party_provenance.py --release-ready
 
@@ -179,6 +165,7 @@ jobs:
           tests/test_voice_backend_registry.py
           tests/test_mic_descriptor.py
           tests/test_aec_native_smoke.py
+          tests/test_aec_build_contract.py
           tests/test_playback_device_recovery.py
           tests/test_tts_contract.py
           tests/test_tts_fish_audio_backend.py

LICENSES/provenance.json

@@ -385,7 +385,7 @@
       "modified": true,
       "release_action": "include",
       "gate_status": "ready",
-      "notes": "Linux-only path source. The sole upstream source patch forces bundled Abseil in Meson setup. Original nested notices are retained and copied into wheel package data. See the adjacent provenance and patch files for verification and removal conditions."
+      "notes": "Linux-only path source. The build-only patch forces and verifies bundled Abseil, isolates setuptools/Meson writes in a disposable source copy, checks wrapper/proxy version consistency before native work, and compiles the committed SWIG bindings. Original generated bindings, runtime sources and nested notices are retained. See the adjacent provenance and complete patch for verification and removal conditions."
     },
     {
       "id": "bokuweb-zstd-wasm",

THIRD_PARTY_NOTICES.md

@@ -19,7 +19,10 @@ the cu124 dependency audit and future SBOM rather than duplicated here.
 ### aec-audio-processing (Linux source build)
 
 - Baseline: official PyPI `aec-audio-processing` 1.0.1 sdist.
-- Local change: one Meson argument forces bundled Abseil for this build.
+- Local build changes: force and verify bundled Abseil, stage setuptools/Meson
+  writes in a disposable source copy, and compile the committed SWIG bindings.
+  A pre-build check rejects inconsistent or unreadable wrapper/proxy versions,
+  including local files regenerated by an earlier installation.
 - Provenance and removal: `vendor/aec-audio-processing.PROVENANCE.md`.
 - Complete bundled license/attribution texts are preserved in the source tree
   and in `vendor/aec-audio-processing/src/files/THIRD_PARTY_NOTICES.txt`, which

docs/alpha-0.17.1.md

@@ -5,6 +5,22 @@ Baseline: `v0.17.0-alpha.0`. This remains a **source Alpha release**.
 Desktop installers, voice/model weights, character media, reference recordings
 and credentials are not included in the source ZIP.
 
+## Post-release Linux Voice upgrade note (#249)
+
+The AEC build repair in #249 is a follow-up and is **not included in the
+`v0.17.1-alpha.0` tag**. Older Linux builds may have left locally regenerated
+SWIG files and `vendor/aec-audio-processing/webrtc-audio-processing/install/`.
+After updating to the fixed revision, back up intentional vendor source edits,
+restore the committed `vendor/aec-audio-processing/src` bindings, and remove
+that obsolete install directory after checking its contents. Mixed wrapper/proxy
+versions now fail before native build work; no files are restored or deleted
+automatically. See the [Linux upgrade steps](install_profiles.md#upgrading-an-existing-linux-voice-checkout).
+The reporter completed the original Arch/system-Abseil-20260817 acceptance on
+`94b584c`, including a separate clean-source/cache/environment retest. See the
+[Arch acceptance report](https://github.com/Code-Amadeus/Amadeus/issues/247#issuecomment-6310492090)
+for the tested environment and scope; this does not establish all-distribution
+or audio-device qualification.
+
 ## Application and dictionary in one Release
 
 The application Release contains its source ZIP, source manifest, checksums and

docs/install_profiles.md

@@ -104,15 +104,47 @@ code, weights, configured interpreter selection, or GPU qualification.
 
 On Ubuntu 24.04, install `build-essential`, `pkg-config` and `portaudio19-dev`,
 then run `uv sync --locked --extra voice` and the `--profile voice` verifier.
-The Linux-only AEC source override uses the official 1.0.1 sdist with one Meson
-argument forcing bundled Abseil 20240722.0. It does not modify system Abseil or
-change the Windows/macOS registry source. See [AEC provenance](../vendor/aec-audio-processing.PROVENANCE.md)
+The Linux-only AEC source override uses the official 1.0.1 sdist, forces and
+verifies bundled Abseil 20240722.0, and stages setuptools/Meson writes in a
+disposable source copy. It compiles the committed SWIG wrapper/proxies after
+checking their version consistency; installation no longer invokes SWIG.
+It does not modify system Abseil or change the Windows/macOS registry source.
+See [AEC provenance](../vendor/aec-audio-processing.PROVENANCE.md)
 for the artifact hash, patch, notices and removal conditions.
 
 The Linux Voice CI uses a fresh uv cache, builds the path dependency and checks
 the actual Meson options/subproject version. It qualifies this source-build
 path on Ubuntu 24.04, not every Linux toolchain or real audio-device behavior.
 
+### Upgrading an existing Linux Voice checkout
+
+An older build may have regenerated only `audio_processing_wrap.cpp` and
+`webrtc_audio_processing.py`, leaving the public `audio_processing.py` at a
+different SWIG version. Updating Git preserves those local edits. The new
+build rejects this mismatch before native library lookup or compilation,
+rather than overwriting the user's files.
+
+Inspect and back up any intentional changes under the vendor `src/` directory.
+From the repository root **after updating to the fixed revision**, restore the
+committed bindings:
+
+```bash
+git restore --source=HEAD -- vendor/aec-audio-processing/src
+```
+
+Remove the old generated
+`vendor/aec-audio-processing/webrtc-audio-processing/install/` directory after
+confirming it contains only the previous build's output. The new backend
+excludes old build/install directories from staging and does not delete them
+from the checkout. Then rerun `uv sync --locked --extra voice` and the Voice
+verifier. For a source archive, unpack a fresh fixed archive instead of using
+`git restore`.
+
+For source-build qualification, run
+`UV_CACHE_DIR="$(mktemp -d)" python3.12 tools/verify_aec_source_build.py`.
+The tool requires Python 3.12 and pins the locked install, both distribution
+builds, and the isolated wheel environment to that interpreter.
+
 ## Optional model interpreters and community configurations
 
 A single default environment does not prohibit isolated model processes. Qwen ASR