QVAC-19255 tts-ggml: enable Supertonic GPU via tts-cpp 2026-06-05

[ogad-tether]

Summary

Companion to tetherto/qvac-registry-vcpkg#184 (now merged at bb702251). That PR bumps the tts-cpp port to master HEAD 128dae42 (PR #31 supertonic_optimizations) which brings the QVAC-18605 Supertonic Vulkan/Metal optimisations (rounds 1-13, ~34× realtime on Apple M-series Metal) and the QVAC-19254 sched + cpu_backend refactor for Adreno OpenCL. This PR removes the now-stale Supertonic is CPU-only today rejection gates on the downstream tts-ggml addon and lets caller GPU intent flow through to the merged tts-cpp tier policy.

C++ addon (addon/src/model-interface/supertonic/)

• SupertonicModel.cpp::validateConfig — removed the if (wantsGpu) { throw StatusError(... "CPU only today" ...) } block. The cross-field conflict check (useGPU=true + nGpuLayers=0, or useGPU=false + nGpuLayers!=0) is preserved so callers can't silently get the opposite backend they asked for.
• SupertonicModel.cpp::loadLocked — removed the #ifdef __ANDROID__ force-off block. Android GPU routing is now delegated to tts-cpp's init_gpu_backend, which already allowlists Qualcomm Adreno (Adreno 700+ → OpenCL, otherwise tier fallback) and skips Mali / non-Adreno GPUs.
• SupertonicConfig.hpp — updated the useGpu docstring.

JS addon (index.js)

• Removed the parallel wantsGpu rejection for Supertonic.
• The default precondition for useGPU = false now also requires nGpuLayers == null so a caller passing nGpuLayers: 99 alone doesn't get a silent conflict with the JS-side default.
• The engine-agnostic conflict check is preserved verbatim.

Tests

• addon/tests/test_supertonic_config.cpp — flipped UseGpuTrueRejectedWithExplanation → UseGpuTrueAcceptedAtConstruction, NGpuLayersGreaterThanZeroRejected → NGpuLayersGreaterThanZeroAccepted. Added UseGpuNGpuLayersConflictStillRejected to lock in the kept conflict check. Simplified NGpuLayersZeroAcceptedAndDeferredLoad.
• test/integration/gpu-smoke.test.js — flipped the Supertonic entry from "useGPU=true is rejected at constructor" to "useGPU=true must engage the GPU backend on GPU-capable platforms", mirroring the existing Chatterbox GPU smoke contract (assertGpuBackend, NO_GPU skip, same loadSupertonicTTS / runSupertonicTTS plumbing).
• test/unit/supertonic{,-mtl}.inference.test.js — updated stale assertion text.

Docs

• README.md, index.d.ts — updated to describe the engine-agnostic tier policy; no more "Supertonic stays CPU-only" claims.
• examples/supertonic*-tts.js (4 files) — NOTE blocks rewritten to reference the new GPU support and point at the opt-in pattern; the examples themselves keep useGPU=false so they run identically everywhere.

Version + dependency

• vcpkg.json — tts-cpp version>= bumped from 2026-06-03#1 to 2026-06-05 (the registry baseline after feat(qvac-lib-registry-client): add findBy() method using schema's findBy #184).
• package.json — 0.2.0 → 0.2.1.
• CHANGELOG.md — new [0.2.1] - 2026-06-05 entry under "Added" + "Changed".

Validation

• Upstream tts-cpp (prior to bump): 38/38 supertonic ctests pass on master HEAD 128dae42.
• Local bench (n=10 timed runs, "quick brown fox", on Apple M-series):
  • C++ Metal native: 92 ms / 0.029 RTF / 34.07× realtime
  • C++ Vulkan via MoltenVK: validates end-to-end (backend: Vulkan0 (device 0: Apple M2), all auto-policies engaged); 33.94× on sustained 11s-audio payloads
  • C++ CPU: 231 ms / 13.57×
  • ONNX CPU contrast: 139 ms / 22.40×
• TTS GGML overlay CI on tetherto/qvac (actions/runs/27006424023): 26/27 jobs pass against the merged tts-cpp; the one failure is the structural merge-guard / validate-pr "needs 'verified' label" check that fires on every workflow_dispatch run regardless of code.
• Local on this branch:
  • npm run test:unit → 61/61 brittle-bare tests pass / 204/204 assertions
  • npm run test:dts → clean
  • standard lint on edited files → clean
• Adversarial subagent review on this diff: SAFE on all 13 invariants (rejection paths cleanly removed, conflict check preserved, Chatterbox untouched, tests correctly inverted, no dangling refs to the old "CPU only today" claim outside historical CHANGELOG entries).

Test plan

• JS unit tests pass locally (npm run test:unit)
• TypeScript .d.ts compiles (npm run test:dts)
• standard lint clean on edited files
• No production-code references to "CPU only today" / "Supertonic is CPU-only" / "silently wrong" (only historical CHANGELOG entries retain the phrase, as is proper for an immutable changelog)
• CI green on this PR (C++ unit tests + integration tests, including the GPU smoke contract on every CI runner that doesn't set NO_GPU=true)
• Real Adreno 700+ device validation (open from the upstream tts-cpp PR testing all trigger reusable lib workflow #31 test plan; not blocking this PR)

🤖 Generated with Claude Code

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ✅ APPROVED

**Requirements:**
- 1 Team Member approval ✅ (1/1)
- 1 Team Lead OR Management approval ✅ (1/1)



---
*This comment is automatically updated when reviews change.*

[freddy311082]

/review