feat(core): compile-time voice feature gate (voice + audio_toolkit) (#4803)

[oxoxDev]

Summary

• Adds a compile-time Cargo voice feature (default-ON) that gates the voice + audio_toolkit domains, composing with the runtime DomainSet.voice flag from feat(core): DomainSet on CoreBuilder + DomainRegistration filter seam (feature-gate prerequisite) #4796.
• Default build is byte-identical — the desktop/CLI app is unchanged. A slim build drops the domains, their controllers/tools, and the hound + lettre deps.
• Uses a stub-facade: pub mod voice; stays compiled either way (real code under #[cfg(feature="voice")], no-op/disabled-error stubs when off), so the ~22 always-on / other-gated callers of voice:: need no per-call #[cfg].
• Pathfinder for the sibling gates (feat(core): feature gate — flows/workflows #4797–feat(core): feature gate — web3 #4802, feat(core): feature gate — media generation #4804): establishes the facade+stub pattern, the slim-profile convention, and a CI smoke lane that builds with the gate OFF.

Problem

#4795 wants one compile-time feature gate per subsystem family so slim harness builds drop code + deps; #4796 shipped the runtime DomainSet axis. This PR adds the compile-time half for voice. Two scope realities the issue under-stated, confirmed by a full sweep:

• whisper-rs / llama are NOT dropped by this gate. They live in the inference domain (src/openhuman/inference/local/service/whisper_engine.rs); cpal is shared with accessibility. Only hound (voice) and lettre (audio_toolkit) are exclusive to the gated domains. Whisper awaits a separate future inference gate. The issue-level DoD line claiming whisper drops is superseded (noted in AGENTS.md).
• voice is widely consumed (credentials startup, channels reply-speech/STT, dictation websocket, socketio, meet_agent, desktop_companion) — ~22 call sites — so it cannot be a clean leaf removal.

Solution

• Cargo.toml: hound + lettre → optional = true; voice = ["dep:hound", "dep:lettre"]; voice added to default.
• Facade (src/openhuman/voice/mod.rs): real submodules + inference re-exports are #[cfg(feature="voice")]; new src/openhuman/voice/stub.rs (#[cfg(not(feature="voice"))]) re-exposes the exact caller surface (server, dictation_listener, streaming, reply_speech, cloud_transcribe, cli, create_stt_provider, effective_stt_provider, publish_ptt_transcript_committed) with no-op / None / disabled-error bodies matching the real signatures.
• audio_toolkit: whole module #[cfg(feature="voice")]; its 3 podcast agent tools + registration + the voice controller/CLI registration in src/core/all.rs are #[cfg]'d out when off.
• CI: new rust-feature-gate-smoke lane runs cargo check --no-default-features --features tokenjuice-treesitter — the disabled build is the only thing that catches stub-signature drift, so it must run in CI.
• Slim-profile convention (no full meta-feature): cargo build --no-default-features --features "<explicit gates>". Documented in AGENTS.md.

When off: voice/audio controllers are unknown-method over /rpc and absent from /schema, the audio_generate_podcast tools are absent, openhuman voice returns a disabled error.

Submission Checklist

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy
• N/A: no instrumented changed lines — the diff is compile-config only (#[cfg] attrs, optional deps, a cfg(not(feature="voice")) stub module not compiled in the default/coverage build, docs, CI yaml). diff-cover reports "no lines with coverage information"; the two new registration tests cover the on/off behavior. CI coverage-gate authoritative. — Diff coverage ≥ 80%
• Coverage matrix updated — N/A: compile-time build-config change, no user-facing feature row
• All affected feature IDs from the matrix are listed in the PR description under ## Related — N/A: no matrix rows affected
• No new external network dependencies introduced (mock backend used per Testing Strategy)
• N/A: default build is byte-identical; the gate only removes surface when explicitly disabled — Manual smoke checklist
• Linked issue closed via Closes #NNN in the ## Related section

Impact

• Desktop / CLI / mobile / web: no behavior change — default build keeps voice on and is byte-identical.
• Slim builds: --no-default-features drops the voice/audio domains + hound/lettre. Note: whisper/cpal are NOT dropped (inference-owned).
• Soft dependency: with {voice: off} but Meet/companion on, their speech paths hit the disabled stubs (transcription/synthesis no-op, not a crash). Acceptable for slim profiles; whether the Meet gate should imply voice is a follow-up.
• Security / migration: none. Additive, default-preserving.

Related

• Closes: feat(core): feature gate — voice #4803
• Epic: Feature gates for core subsystems — tracking (lightweight harness builds) #4795 (Milestone M1). Composes with the feat(core): DomainSet on CoreBuilder + DomainRegistration filter seam (feature-gate prerequisite) #4796 runtime DomainSet seam. Follow-up (per @M3gA-Mind on feat(core): runtime DomainSet composition axis — group-tagged registry + ambient filter (#4796) #4808): feat(core): converge tool gating with controller gating via per-Tool DomainGroup metadata #4821 tool/controller gating convergence.

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Linear Issue

• Key: N/A
• URL: N/A

Commit & Branch

• Branch: feat/4803-voice-feature-gate
• Commit SHA: d48ae12fd17b2d07e23a26818a10e227d84681c9

Validation Run

• N/A: no app/ (frontend) changes — pnpm --filter openhuman-app format:check
• N/A: no TypeScript changes — pnpm typecheck
• Focused tests: core::all::tests::voice_and_audio_controllers_registered_when_feature_on (default) + ..._absent_when_feature_off (disabled), core::all 50 passed, openhuman::voice/openhuman::audio_toolkit green
• Rust fmt/check (if changed): cargo fmt --check clean · default cargo check exit 0 · disabled cargo check --no-default-features --features tokenjuice-treesitter exit 0 · cargo clippy --lib 0 warnings in changed files (both configs)
• N/A: no app/src-tauri changes — Tauri fmt/check

Validation Blocked

• command: cargo test --lib (full)
• error: OOM on local machine (known)
• impact: full matrix runs in CI; locally scoped to voice/audio_toolkit/core::all/tools::ops — all green in both feature configs

Behavior Changes

• Intended behavior change: new default-on voice compile-time gate; default unchanged
• User-visible effect: none by default; slim builds omit voice/audio domains + deps

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d48ae12fd1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Wire feature-gate smoke into the PR gate

In PRs where the repository rules only require the historical PR CI Gate check (the workflow comment says that name is kept for the ruleset), this new smoke job can fail without blocking merge because pr-ci-gate neither lists rust-feature-gate-smoke in its needs nor checks its result. That defeats the stated purpose of this lane: a future stub-signature drift in --no-default-features --features tokenjuice-treesitter could be red in CI while the required gate still passes.

Useful? React with 👍 / 👎.