From 01221769cd67a15111358be2da20526687663223 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sun, 5 Jul 2026 19:10:19 +0100 Subject: [PATCH] added agendo about background service (music player as example) --- discussion/index.ndjson | 3 +- ...0048-background-service-audio-execution.md | 208 ++++++++++++++++++ 2 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 discussion/workflow/agendas/AGD-0048-background-service-audio-execution.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 6e4ca8a2..9da61ed1 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":45,"AGD":48,"DEC":41,"PLN":167,"LSN":55,"CLSN":1}} +{"type":"meta","next_id":{"DSC":46,"AGD":49,"DEC":41,"PLN":167,"LSN":55,"CLSN":1}} {"type":"discussion","id":"DSC-0044","status":"done","ticket":"hub-suspended-game-kill-affordance","title":"Hub Suspended Game Kill Affordance","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["hub","lifecycle","game","ui"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0054","file":"discussion/lessons/DSC-0044-hub-suspended-game-kill-affordance/LSN-0054-manual-hub-kill-must-share-game-termination-cleanup.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]} {"type":"discussion","id":"DSC-0043","status":"done","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0043-system-os-cartridge-switch-orchestrator/LSN-0053-game-switching-is-lifecycle-replacement-not-loader-work.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]} {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."} @@ -19,6 +19,7 @@ {"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0045","status":"open","ticket":"background-service-audio-execution","title":"Background Service and Audio Execution","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","service","audio","background","architecture"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-background-service-audio-execution.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0009","status":"done","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-07-01","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md","status":"done","created_at":"2026-07-01","updated_at":"2026-07-01"}]} {"type":"discussion","id":"DSC-0010","status":"done","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0010-perf-host-desktop-frame-pacing-and-presentation/LSN-0036-frame-publication-and-host-invalidation-must-be-separate.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20"}]} diff --git a/discussion/workflow/agendas/AGD-0048-background-service-audio-execution.md b/discussion/workflow/agendas/AGD-0048-background-service-audio-execution.md new file mode 100644 index 00000000..b53f9a28 --- /dev/null +++ b/discussion/workflow/agendas/AGD-0048-background-service-audio-execution.md @@ -0,0 +1,208 @@ +--- +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. +