---
id: AGD-0048
ticket: background-service-audio-execution
title: Agenda - Background Service and Audio Execution
status: open
created: 2026-07-05
resolved:
decision:
tags: [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:

```text
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.