prometeu-runtime/docs/pull-requests/PR-005-host-audio-fallible-init-and-headless-tolerance.md

PR-005: Host Audio Fallible Init and Headless Tolerance

Briefing

O host desktop atual assume que audio de saida esta sempre disponivel e funcional. Em ambientes headless, CI, VMs remotas ou sistemas sem device compativel, a inicializacao usa expect(...) e encerra o processo.

Este PR torna a pilha de audio tolerante a falhas de infraestrutura. O runtime deve continuar operando sem audio quando o host nao puder inicializar a saida sonora.

Problema

• default_output_device() pode retornar None.
• build_output_stream(...) pode falhar por formato/configuracao.
• stream.play() pode falhar por indisponibilidade do backend.
• Todas essas falhas hoje derrubam o binario com panic!.

Escopo

• Trocar inicializacao panica por API fallible.
• Permitir degradacao controlada para "sem audio".
• Manter telemetria/log suficiente para diagnostico.
• Cobrir o fluxo em testes de unidade onde viavel.

Fora de Escopo

• Rework do mixer.
• Selecao automatica de formatos de audio mais sofisticada.
• Hot-reload de device de audio.
• Simulacao de audio em buffer offline.

Abordagem

1. Mudar HostAudio::init para retornar Result<(), HostAudioError> ou tipo equivalente.
2. Representar explicitamente o estado "audio indisponivel":
   • producer = None
   • stream = None
   • stats continuam funcionando sem crash.
3. No chamador, registrar aviso e seguir execucao sem audio.
4. Garantir que send_commands e update_stats sejam no-op seguros quando o audio nao estiver ativo.

Algoritmo

Inicializacao

1. Buscar default_output_device.
2. Se nao existir:
   • retornar erro de inicializacao controlado.
3. Tentar construir StreamConfig e build_output_stream.
4. Se falhar:
   • retornar erro controlado sem panicar.
5. Tentar play().
6. Se falhar:
   • retornar erro controlado sem panicar.
7. Apenas em caso de sucesso preencher producer, perf_consumer e _stream.

Degradacao

1. O host chama init.
2. Se Ok, audio ativo.
3. Se Err, loga a falha e continua sem audio.
4. O loop principal segue responsivo e funcional.

Criterios de Aceite

• O runtime nao entra em panic! quando nao existe device de audio.
• O runtime nao entra em panic! quando build_output_stream falha.
• O runtime nao entra em panic! quando play() falha.
• send_commands e update_stats continuam seguros sem stream ativo.
• O host continua executando cartridge em modo sem audio.
• Logs deixam claro por que o audio foi desativado.

Tests

• Introduzir testes de unidade para o estado sem audio:
  • send_commands nao falha quando producer e None;
  • update_stats nao falha quando perf_consumer e None.
• Se a estrutura atual permitir injecao de dependencia:
  • testar caminho no output device;
  • testar falha na criacao do stream;
  • testar falha no play.
• Se injecao ainda nao existir, criar uma camada minima de abstracao para tornar esses cenarios testaveis sem depender do hardware real.
• Rodar:
  • cargo test -p prometeu-host-desktop-winit
  • cargo test --workspace

Risco

Baixo. A mudanca principal e de robustez operacional. O maior cuidado e nao esconder a falha completamente; o modo sem audio precisa ser explicito em logs.