prometeu-runtime/discussion/workflow/agendas/AGD-0048-background-service-audio-execution.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0048	background-service-audio-execution	Agenda - Background Service and Audio Execution	open	2026-07-05			runtime os lifecycle service audio background architecture

Agenda - Background Service and Audio Execution

Contexto

O runtime ja tem sinais claros de preparacao para multitarefa controlada:

• TaskState::Background existe como estado de tarefa;
• VmSession separa estado mutavel de VM por tarefa/processo;
• SystemOS e dono de lifecycle, task/process, VM sessions, filesystem, memcard, windows e logging;
• a spec de eventos separa foreground ownership de execution eligibility;
• o contrato atual declara que execucao real em background fica fora do v1, mas o modelo foi desenhado para permitir servicos ou processos de midia no futuro.

O caso motivador e:

Game foreground -> Home -> music player -> escolher musica -> voltar ao Game

Depois disso, o Game deve voltar ao foreground enquanto o player continua executando e produzindo audio junto com audio do Game.

Problema

Hoje o runtime preserva sessoes, mas nao tem contrato para uma sessao continuar executando quando nao e foreground.

Os pontos atuais que bloqueiam o caso:

• TaskKind so distingue Game e Shell;
• ProcessKind so distingue VmGame, VmShell e NativeShell;
• ProcessState nao possui estado normativo de background-running;
• GameRunningStep ticka apenas o Game foreground;
• ShellRunningStep ticka apenas o Shell foreground;
• HubHomeStep nao ticka sessoes VM em background;
• Audio e AudioMixer usam vozes globais sem namespace por tarefa/sessao;
• cada logical frame chama platform.audio_mut().clear_commands(), o que torna perigoso tickar dois produtores de audio no mesmo frame;
• pausa de lifecycle hoje emite MasterPause, afetando o mixer inteiro.

Sem uma decisao, background service pode virar apenas "tickar mais uma VM", mas isso quebraria isolamento, audio, debugger, lifecycle e previsibilidade.

Pontos Criticos

1. Execution eligibility nao e foreground. O contrato atual ja separa os conceitos, mas a implementacao ainda so ticka o owner foreground. Precisamos introduzir uma politica explicita de quem pode executar em background.

2. Servico nao e Shell escondido. Um music player pode ter UI de Shell para escolher musica, mas a reproducao continua como servico quando a UI deixa o foreground. Fechar isso como Shell em background confundiria janela, tarefa, sessao e servico.

3. Audio precisa de origem. Hoje voice_id e global no mixer. Se Game e player usam voice_id = 0, um sobrescreve o outro. Precisamos decidir se o mixer tera namespaces por AudioOwner, se servicos terao pool dedicado, ou se o player nao usara a mesma superficie audio.*.

4. Pausa de Game nao pode pausar servico de midia. MasterPause global serve para o contrato atual de pausa/debug, mas nao expressa "pausar Game audio e manter music player". Pausa precisa virar escopo por origem ou politica de mixer.

5. Servico precisa de lifecycle proprio. Deve existir contrato para start, foreground UI, background-running, stop, crash, terminate, recurso negado, e talvez wake/resume de UI.

6. Budget e determinismo precisam ser fechados. Se servicos rodam junto com Game, precisamos decidir cota por frame, ordem de ticks, starvation, crash isolation, e se background service participa do mesmo tempo deterministico da maquina.

7. Sistema de apps precisa descobrir e lancar o player. Hoje Home lista Game cartridges e tem Shells nativos fixos. O caso de music player exige decidir se ele e cartridge System, app instalado, Shell nativo, ou novo perfil Service.

Opcoes

Opcao A - Background Service como novo tipo de processo/sessao

Criar contrato explicito para Service:

• TaskKind::Service ou entidade equivalente;
• ProcessKind::VmService / NativeService;
• execution eligibility independente de foreground;
• UI de controle opcional via Shell task associada ao servico;
• audio com origem por service/session;
• lifecycle proprio: start, background, foreground-control, stop, crash.

Pros:

• modela diretamente music player e futuros servicos;
• preserva a separacao entre UI foreground e execucao;
• evita transformar Shell em "processo que tambem e daemon";
• facilita quotas, permissao e observabilidade.

Contras:

• maior mudanca arquitetural;
• exige novo contrato em specs, SystemOS, firmware, audio e testes;
• precisa fechar politica de recursos antes de implementar.

Manutencao:

• melhor base para crescer com qualidade, desde que o MVP seja pequeno.

Opcao B - Shell em background com audio permitido

Permitir que uma VM Shell continue tickando quando sai do foreground e use audio normalmente.

Pros:

• reaproveita Shell, WindowManager e VM session existentes;
• menor numero de novos tipos no curto prazo.

Contras:

• mistura UI e servico;
• torna TaskState::Background semantico antes de definir ProcessState;
• abre precedente para qualquer Shell continuar executando;
• nao resolve sozinho namespace de audio, pause por origem, quotas e debugging.

Manutencao:

• atraente como atalho, mas tende a espalhar excecoes pela firmware state machine.

Opcao C - Audio player como servico nativo OS-owned, sem VM background

Implementar music player como servico nativo de SystemOS, controlado por uma Shell UI. A reproducao continua no host/OS sem tickar VM em background.

Pros:

• entrega o caso de musica com menor risco para scheduler VM;
• evita abrir execucao arbitraria de background agora;
• audio service pode ser projetado como recurso OS-owned e depois exposto.

Contras:

• nao resolve background VM services em geral;
• player deixa de ser app userland completo no primeiro ciclo;
• precisa ainda fechar origem/mixagem de audio e relacao com UI.

Manutencao:

• bom MVP se o objetivo imediato for media playback, mas deve ser declarado como media service nativo, nao como contrato geral de background VM.

Sugestao / Recomendacao

Recomendo fechar em duas camadas:

1. Decisao de arquitetura: introduzir o conceito de service/background execution como contrato de SystemOS, separado de foreground Shell e Game. Essa decisao deve definir execution eligibility, lifecycle, quotas, crash policy, controle de UI e relacao com VM sessions.

2. MVP de media: implementar primeiro um media/audio service com escopo reduzido, preferencialmente OS-owned ou Service bem delimitado, antes de permitir background VM arbitrario.

Para excelente qualidade, o primeiro plano nao deve tentar "qualquer app em background". O alvo deve ser: um unico servico de audio/midia, com origem de audio propria, controle por Hub/Shell, execucao enquanto Game esta foreground, e testes end-to-end de mistura e lifecycle.

Perguntas em Aberto

• O music player deve ser um cartridge System, um novo Service, ou um servico nativo do OS controlado por Shell?
• A UI do player e a reproducao pertencem a mesma tarefa ou a tarefas separadas?
• Um servico pode ter janela foreground temporaria e continuar sem janela?
• Quantos servicos background podem existir no MVP: um media service ou N servicos?
• O background service recebe ticks todo frame, tick rate reduzido, ou apenas eventos?
• O audio mixer deve isolar vozes por TaskId, ProcessId, VmSessionId, AppId, ou novo AudioOwner?
• Como pausar apenas o audio do Game durante Home/debug sem pausar musica?
• O debugger inspeciona foreground session apenas ou tambem sessoes background?
• Como crash de servico e exibido: toast/log, janela de crash, ou parada silenciosa com diagnostico?
• Que capacidades sao necessarias para media service: audio, fs, asset, talvez background_audio?

Criterio para Encerrar

Esta agenda pode virar decisao quando houver resposta escrita para:

• modelo de entidade (Service novo vs Shell background vs native OS service);
• execution eligibility e ordem de ticks;
• lifecycle e estados de task/process;
• ownership/namespace de audio e politica de pausa por origem;
• relacao entre UI foreground do player e reproducao background;
• escopo do MVP e explicitamente o que fica fora;
• testes obrigatorios de lifecycle, audio mixing, crash isolation e regressao do contrato Game/Home/Shell existente.