housekeep

This commit is contained in:
2026-04-07 05:33:18 +01:00
parent 49b2715158
commit 5b03fe6cfd
13 changed files with 58 additions and 1437 deletions
@@ -1,186 +0,0 @@
---
id: AGD-0009
ticket: studio-debugger-workspace-integration
title: Integrar ../debugger ao Studio como workspace dedicado
status: in_progress
created: 2026-03-30
resolved: 2026-04-06
decision: DEC-0022
tags:
- studio
- debugger
- workspace
- integration
- shell
---
## Pain
O shell do Studio ja anuncia `WorkspaceId.DEBUG` e exibe `Debug` na workspace rail, mas nao registra nenhum workspace concreto para esse slot.
Hoje isso deixa o produto num estado inconsistente:
- a shell promete um `Debugger/Profiler` como workspace baseline;
- `MainView` publica a opcao `Debug` na navegacao;
- `WorkspaceHost` exige que o workspace esteja registrado;
- a implementacao real do `Debug` continua fora do Studio, no sibling repo `../debugger`.
Sem uma discussion canonica, a integracao tende a cair em um de tres atalhos ruins:
- abrir o debugger como app externo e fingir que isso equivale a um workspace;
- embutir a aplicacao JavaFX existente dentro do Studio sem alinhar ciclo de vida, eventos e theming;
- reescrever tudo no Studio e perder o que o `../debugger` ja estabilizou em protocolo, controle de execucao e estado.
## Context
Domain owner: `studio`
Owner surface: `docs/specs/studio`
Cross-domain input: sibling repo `../debugger`
Normative upstream dependencies:
- `DEC-0020` for `Play` preparation through `build -> validate pack -> pack -> manifest`
- `DEC-0021` for runtime execution through external `"<runtimePath>" run build` and `Play/Stop` process ownership
Superficies relevantes hoje:
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` ja define `Debugger/Profiler` como parte do baseline workspace set;
- `docs/specs/studio/2. Studio UI Foundations Specification.md` exige um modelo de workspaces orientado a eventos, com bus por workspace e republishing para o bus global;
- `prometeu-studio/src/main/java/p/studio/window/MainView.java` ja inclui `WorkspaceId.DEBUG` na rail, mas o `register(...)` correspondente esta comentado;
- `prometeu-studio/src/main/java/p/studio/workspaces/Workspace.java` exige um contrato de `rootNode()`, `load()`, `unLoad()` e integra o workspace a um `StudioWorkspaceEventBus`;
- `../debugger` ja existe como aplicacao JavaFX separada, com `Application`/`Stage`, FXML, Dagger, i18n, cliente DevTools, protocolo TCP/JSONL e controle de execucao.
O boundary de produto tambem ja aponta a direcao correta:
- o shell do Studio deve enquadrar workspaces sem absorver detalhe operacional;
- logs e detalhe de execucao pertencem ao workspace que os possui;
- o debugger e uma superficie de execucao, nao um detalhe lateral do painel global de utilidades.
As discussoes mais recentes de `Play/Stop` tambem reduziram o primeiro corte que interessa agora:
- o `DebugWorkspace` e o destino futuro dos logs de `build`, validacao de `pack`, `pack` e runtime;
- `Play/Stop` continua dono do fluxo operacional de `run` nesta wave;
- o valor principal a reaproveitar do `../debugger` agora esta em filosofia, politicas de debug/remote connection, sessao, protocolo e modelos de eventos, nao em bootstrap de app standalone nem em copia literal de codigo;
- o objetivo imediato nao e portar "o debugger inteiro", mas sim dar ao Studio uma superficie de execucao e observabilidade nativa.
- nao precisamos comecar perfeitos: a primeira wave pode ser deliberadamente simples, desde que entregue handshake com o runtime e sink de logs suficiente para destravar `Play/Stop`.
Constraint for this agenda:
- esta agenda trabalha em conjunto com `AGD-0023`/`DEC-0020` e `AGD-0024`/`DEC-0021`;
- ela NAO pode reinterpretar pipeline de preparacao, politica de execucao, ownership de `Play/Stop` ou trocar `run` por `debug` por inferencia;
- qualquer mudanca nesses contratos exige revisao explicita das decisions upstream, nao convergencia lateral dentro desta agenda.
## Open Questions
- [x] O objetivo da primeira integracao e hospedar a experiencia atual do `../debugger` quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio?
- Resposta proposta: o primeiro corte deve ser menor e nativo ao contrato de workspace do Studio, focado em sink de logs de execucao/preparacao e politicas de debug/remote connection.
- [x] Quais partes do `../debugger` sao `core` reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira?
- Resposta proposta: o `../debugger` deve ser tratado principalmente como referencia filosofica e arquitetural; sessao, protocolo, cliente de remote connection, politicas de debug e modelos de eventos/estado podem ser reaproveitados quando isso for util, mas nao ha autorizacao para copiar codigo 1:1 por inercia. Bootstrap `Application`/`Stage`, shell standalone e UI acoplada a esse host nao devem atravessar a fronteira como unidade de integracao.
- [x] Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo?
- Resposta proposta: a topologia correta desta integracao e migracao seletiva para dentro do Studio, sem link tecnico entre os dois projetos. `../debugger` nao deve virar dependencia viva do Studio porque sera removido em breve. Copia 1:1 deve ser evitada por padrao, mas pode acontecer pontualmente quando for realmente util.
- [x] Os detalhes do handshake com o runtime ja precisam nascer totalmente redesenhados no Studio, ou podem ser tirados do `../debugger` nesta wave?
- Resposta proposta: os detalhes do handshake podem ser tirados do `../debugger` nesta wave, desde que entrem no Studio no shape nativo do workspace e sem copiar codigo 1:1 por inercia.
- [x] Quem passa a ser o owner do ciclo de vida da sessao de debug: o `DebugWorkspace`, a shell do Studio, ou um servico compartilhado com a run surface?
- Resposta proposta: o owner deve ser um servico/sessao compartilhado consumido pelo `DebugWorkspace`, enquanto `Play/Stop` continua acionando connect/attach/disconnect under the hood nesta wave.
- [x] Como eventos, telemetria, logs e estados do debugger entram no bus de workspace e no bus global sem criar um segundo sistema paralelo de notificacao?
- Resposta proposta: `build` e `pack` permanecem owners de seus proprios logs, mas esses streams devem ser agregados, merged e sinkados para o destino de logs do `DebugWorkspace`; o workspace repassa apenas eventos resumidos relevantes para o bus global do Studio.
- [x] O primeiro corte deve incluir `profiler` junto com `debugger`, ou o baseline inicial fecha apenas `debugger` e deixa profiling como extensao posterior?
- Resposta proposta: o baseline inicial fecha apenas `debugger`; politicas de connect/disconnect manuais podem ficar mais relevantes quando a wave de profiling existir.
- [ ] Como preservar tema, i18n e consistencia visual se parte da UI atual do `../debugger` ainda estiver em FXML e recursos proprios?
- [x] O app standalone `../debugger` continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario?
- Resposta proposta: o `../debugger` e uma tentativa anterior e sera deletado quando o Studio estiver maduro o suficiente para representa-lo; ele nao deve ser mantido como destino paralelo nem receber novas mudancas durante esta integracao.
- [x] O sink inicial de logs precisa nascer sofisticado, ou uma console/lista simples com origem visivel ja basta nesta wave?
- Resposta proposta: uma console/lista simples com origem visivel ja basta nesta wave; merge e apresentacao podem melhorar depois.
- [x] O `DebugWorkspace` deve abrir ja com estado basico de conexao como `connecting`, `connected` ou `failed`, mesmo com UI ainda crua?
- Resposta proposta: sim; o workspace deve abrir com estado basico de sessao/conexao desde a primeira wave.
## Options
### Option A - Launcher externo a partir do Studio
- **Approach:** O Studio oferece um ponto de entrada para abrir `../debugger` como processo/janela externa, mantendo a integracao dentro da shell apenas como acao de lancamento.
- **Pro:** Menor custo inicial e reaproveitamento maximo da app atual.
- **Con:** Nao entrega um workspace real do Studio, fragmenta estado/sessao e conflita com a baseline shell spec.
- **Maintainability:** Fraca como arquitetura final. Pode servir no maximo como ponte temporaria, mas nao resolve o contrato de workspace.
### Option B - Embutir a UI atual do debugger quase inteira dentro de um workspace host
- **Approach:** Reaproveitar FXML/controllers do `../debugger` e monta-los dentro de um `DebugWorkspace`, fazendo adaptacoes localizadas de DI, lifecycle e navegacao.
- **Pro:** Reaproveita mais UI existente e acelera a primeira tela funcional.
- **Con:** Carrega para dentro do Studio um bootstrap orientado a `Application`/`Stage`, com modelo proprio de lifecycle, theming e eventos que nao casa naturalmente com o contrato de workspace atual.
- **Maintainability:** Media para baixa. Economiza reescrita imediata, mas cristaliza um boundary torto entre app standalone e workspace embutido.
### Option C - Workspace nativo do Studio com migracao seletiva inspirada no debugger
- **Approach:** Tratar o `../debugger` como referencia arquitetural e fonte seletiva de detalhes uteis, migrando para o Studio apenas o que fizer sentido, em shape nativo ao contrato `Workspace` + bus tipado + lifecycle-managed controls, sem criar dependencia tecnica entre os dois repositorios.
- **Pro:** Alinha shell spec, workspace framework e boundary de produto, sem descartar o investimento ja feito no debugger.
- **Con:** Exige separar explicitamente o que e filosofia/padrao reutilizavel, o que e core realmente util e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico.
- **Maintainability:** Forte. Preserva a direcao arquitetural correta e permite absorver o valor estrutural do `../debugger` sem importar o host standalone como boundary errado nem copiar codigo por reflexo.
### Option D - Migracao integral do debugger para dentro do Studio
- **Approach:** Absorver codigo e UI do `../debugger` para dentro dos modulos do Studio e tratar a aplicacao standalone como legado a ser aposentado.
- **Pro:** Simplifica ownership futuro se o produto decidir convergir totalmente para uma unica shell.
- **Con:** E a aposta mais cara e mais irreversivel, antes mesmo de fechar o contrato de integracao e o que ainda deve continuar independente.
- **Maintainability:** Media. Pode ser boa no longo prazo, mas e prematura enquanto o boundary entre `workspace` e `app standalone` ainda nao esta fechado.
## Discussion
O ponto principal nao e "como mostrar alguma tela de debug no Studio". O ponto principal e decidir qual contrato queremos estabilizar entre:
- a shell do Studio, que ja assume workspaces independentes e orientados a eventos;
- o `DebugWorkspace`, que precisa ser um workspace real, com ownership claro de detalhe operacional;
- e o `../debugger`, que hoje concentra bootstrap de app, protocolo, estado e UI numa aplicacao separada.
Mas esse contrato agora tem limites claros:
- `DEC-0020` ja fecha a preparacao;
- `DEC-0021` ja fecha a execucao com `run build` e ownership de processo;
- portanto a agenda 9 so pode definir a superficie que hospeda logs, sessao e politicas remotas compativeis com esses contratos.
O fato de a rail ja ter `Debug` e a spec ja falar em `Debugger/Profiler` indica que a integracao nao e trabalho especulativo.
Ela ja faz parte da topologia esperada do Studio.
Por isso, as opcoes que preservam o debugger apenas como janela externa ou que arrastam a app inteira para dentro do host sem remodelar o boundary resolvem pouco:
- a primeira evita o trabalho agora, mas nao entrega o produto prometido pela shell;
- a segunda reaproveita UI, mas importa um modelo arquitetural que nao conversa bem com `Workspace`, `StudioWorkspaceEventBus`, theming compartilhado e lifecycle-managed controls.
O caminho mais coerente parece ser separar o problema em duas camadas:
1. um `debugger core` reaproveitavel, com sessao, protocolo, telemetria, logs e controle de execucao;
2. uma composicao de `DebugWorkspace` nativa do Studio, que consome esse core como mais um workspace do shell.
As decisoes recentes de `Play/Stop` deixam ainda mais claro o primeiro corte util:
- o `DebugWorkspace` deve receber o sink de logs de `build`, validacao de `pack`, `pack` e runtime;
- `build` e `pack` continuam possuindo seus proprios logs, mas o usuario deve ve-los merged no destino do debugger;
- `Play/Stop` continua fazendo attach/connect/disconnect under the hood nesta wave, sem expor ainda uma superficie rica de comandos manuais;
- o `core` de remote connection e politicas de debug do `../debugger` pode ser reaproveitado aqui;
- profiler fica explicitamente fora do baseline inicial.
Esse recorte tambem assume pragmatismo de wave 1:
- o handshake com o runtime pode nascer a partir dos detalhes ja estabilizados no `../debugger`;
- o sink de logs pode comecar como console/lista simples com origem visivel;
- o `DebugWorkspace` precisa mostrar estado de sessao suficiente para o usuario entender se esta conectando, conectado ou falhou;
- refinamentos de UX, estrutura de logs e comandos mais ricos podem vir depois.
Isso nao obriga uma reescrita total imediata da logica do debugger.
Obriga apenas que a UI e o bootstrap standalone parem de ser tratados como se fossem a fronteira certa de integracao.
## Resolution
Recommended direction: seguir com **Option C**.
A agenda deve convergir para uma decisao com os seguintes fechamentos:
1. `Debug` no Studio deve virar um workspace real, nao apenas launcher de app externo;
2. o `../debugger` deve ser tratado como referencia filosofica e fonte seletiva de reaproveitamento, nao como base para copia 1:1;
3. a topologia desta wave deve ser migracao seletiva sem link tecnico entre os dois projetos;
4. o boundary correto de reaproveitamento esta em servicos/protocolo/estado/politicas de remote connection do debugger, nao no bootstrap `Application`/`Stage` como unidade de integracao;
5. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n;
6. o primeiro corte deve ser focado em sink merged de logs de execucao/preparacao e sessao de debug remota consumida pelo workspace;
7. `Play/Stop` deve continuar controlando under the hood o fluxo de connect/attach/disconnect nesta wave;
8. `profiler` fica explicitamente fatiado para depois;
9. o `../debugger` nao deve receber novas mudancas e sera deletado quando o Studio estiver maduro o suficiente para representa-lo;
10. esta agenda deve permanecer estritamente compativel com `DEC-0020` e `DEC-0021`, sem avancar sinal sobre preparacao ou execucao;
11. a primeira wave nao precisa ser perfeita: basta entregar handshake com o runtime, estado basico de sessao e sink de logs simples com origem visivel, deixando refinamentos para depois.
Next step suggestion: converter esta agenda em uma `decision` que feche o modelo de integracao, o boundary de ownership entre `studio` e `../debugger`, a topologia de dependencias entre repositorios e o escopo da primeira wave de `DebugWorkspace` como superficie nativa de logs/sessao de execucao remota.
@@ -1,132 +0,0 @@
---
id: AGD-0023
ticket: studio-play-stop-cartridge-flow
title: Play/Stop integration agenda for build/pack freshness-gated runtime preparation
status: in_progress
created: 2026-04-06
resolved: 2026-04-06
decision: DEC-0020
tags: [studio, play-stop, build, pack, compiler, packer, manifest]
---
## Pain
O botão `Play` do Studio hoje só alterna estado visual no shell.
Ele ainda não aciona um fluxo operacional real para preparar um conjunto executável de artefatos em `build/`.
Isso deixa o shell com uma affordance de execução sem pipeline correspondente e sem um contrato claro entre:
- Studio shell,
- compiler build,
- compiler,
- packer,
- e a pasta `build/` do projeto.
## Context
Domain owner: `studio`.
Subdomínios referenciados: `compiler`, `packer`, `runtime`.
Já existe um `ShipperWorkspace` no Studio e ele hoje chama `BuilderPipelineService.INSTANCE.build(...)`, mas esse fluxo atual é apenas um scratch inicial.
Na prática, hoje ele está compilando bytecode e não deve ser tratado como o contrato definitivo de preparação de runtime do produto.
O objetivo desta agenda não é fechar um pipeline de shipping nem materializar um `cartridge/` separado.
O escopo desta wave é estritamente o mínimo necessário para o botão `Play` conseguir preparar artefatos rodáveis em `build/`:
1. compilar o PBX necessário;
2. executar o packer necessário;
3. manter ou regenerar os artefatos de `build/` conforme frescor;
4. gerar `manifest.json` em `build/`.
Essa agenda trata apenas da preparação dos artefatos em `build/`.
A execução `runtime run cartridge` ou equivalente apontando para `build/` fica em agenda separada dentro da mesma discussion.
## Open Questions
- [x] O `Play` deve reutilizar exatamente o mesmo pipeline já acionado pelo `ShipperWorkspace`, ou deve haver um service/application layer dedicado para o shell chamar e o workspace apenas consumir?
- Resposta proposta: `Play` não deve reaproveitar o scratch atual do `ShipperWorkspace`; ele deve orquestrar chamadas explícitas de `build` e `pack`, cada uma com sua própria política de frescor.
- [x] Os artefatos rodáveis desta wave devem viver em `cartridge/` separado ou no próprio `build/`?
- Resposta proposta: nesta wave o artifact root runnable deve ser `build/`; não há necessidade de materializar um `cartridge/` separado se o runtime pode consumir o mesmo contrato diretamente de `build/`.
- [x] Quem decide se é necessário recompilar ou repackar quando o usuário aperta `Play`?
- Resposta proposta: nesta wave, `Play` sempre chama `build` e `pack`; a política fina de drift/freshness fica explicitamente adiada para uma segunda etapa. Quando essa segunda etapa existir, cada domínio será owner de sua própria política de frescor.
- [x] Onde deve viver o controle fino de frescor e drift para os artefatos produzidos?
- Resposta proposta: quando a wave de drift existir, o controle fino viverá em arquivos dedicados por domínio sob `.studio/`, começando por `asset-workspace.json` e `editor-workspace.json`, separados do snapshot principal de restauração.
- [x] O `manifest.json` runtime-facing deve ser derivado do `prometeu.json` do projeto com normalização adicional do Studio, ou copiado quase diretamente com apenas os campos estritamente runtime-facing?
- Resposta proposta: o `manifest.json` deve ser sempre gerado de forma determinística em `build/`, a partir do build corrente e do owner metadata do projeto, sem cópia por conveniência.
- [x] Como o shell distinguirá falha de build, falha de pack e falha de manifest para refletir estado útil no `Play/Stop`?
- Resposta proposta: para o `Play`, basta distinguir `success` e `failed`; logs detalhados das operações devem acompanhar o resultado. `build` falhando bloqueia `pack`, e `manifest` só roda depois do sucesso do build/pack desta wave.
## Options
### Option A - `Play` sempre chama `build` e `pack`, e drift fica para uma wave posterior
- **Approach:** Fazer o shell chamar explicitamente `build` e `pack` em toda execução de `Play`; nesta wave não há reuse por drift/freshness, apenas execução determinística com logs e geração final de `manifest.json`.
- **Pro:** Destrava a integração do `Play` com o menor contrato correto, sem antecipar um sistema de freshness ainda não normatizado.
- **Con:** Pode refazer trabalho desnecessário em execuções sucessivas até a wave de drift existir.
- **Maintainability:** Boa, porque mantém o `Play` simples agora e deixa a otimização para uma agenda própria depois.
### Option B - `Play` inspeciona artefatos existentes e decide por conta própria se pode seguir
- **Approach:** O shell observa presença ou timestamps de artefatos em `build/` e tenta inferir se basta reutilizar o que já existe.
- **Pro:** Menos modelagem inicial de metadata e contratos.
- **Con:** Move para o shell uma inteligência que pertence aos domínios de compiler e packer, além de abrir espaço para reuse incorreto sob drift parcial do workspace.
- **Maintainability:** Fraca, porque o `Play` vira owner implícito de políticas que não são dele.
## Discussion
O ponto central aqui não é apenas "rodar compile + packer".
O problema real é separar claramente:
- a orquestração do `Play`,
- a responsabilidade de `build`,
- a responsabilidade de `pack`,
- e a futura política de frescor de cada artefato.
Se o `Play` inferir por conta própria se precisa rebuildar ou repackar, o shell passa a absorver conhecimento que pertence a outros domínios.
Isso cria uma fronteira errada: o shell deixa de ser apenas o caller de operações e passa a ser o árbitro de drift do projeto.
Ao mesmo tempo, modelar agora um sistema fino de drift adicionaria complexidade antes da própria integração básica do `Play` existir.
Por isso, esta agenda fecha a wave 1 com execução sempre explícita e adia a otimização de freshness para uma agenda própria.
O contrato mais limpo é:
1. `Play` pede `build`;
2. `build` executa e retorna `success` ou `failed`, acompanhado de logs;
3. `Play` pede `pack`;
4. `pack` executa e retorna `success` ou `failed`, acompanhado de logs;
5. `manifest.json` é sempre regenerado em `build/` a partir do build corrente e dos metadados do projeto;
6. `Play` só verifica sucesso ou falha dessas operações antes de seguir para a execução.
Os constraints já visíveis no repositório reforçam esse recorte:
- o compiler atual escreve `build/program.pbx`;
- o packer atual escreve `build/assets.pa` e companions de tooling, e o spec do packer afirma explicitamente que cartridge assembly não pertence ao domínio `packer`;
- os projetos de teste já mostram `build/` contendo `program.pbx`, `assets.pa` e companions;
- `ProjectLocalStudioSetup` já está carregado na `StudioProjectSession`, então o shell já possui o owner correto para coordenar preparation + future run sem precisar deduzir drift por presença oportunista de arquivo.
Isso torna a fronteira recomendada mais concreta:
1. `build/` é o artifact root runnable desta wave;
2. compiler e packer continuam donos de seus artefatos dentro de `build/`;
3. `Play` não usa presença de arquivo como regra de validade;
4. drift e freshness ficam explicitamente fora do escopo desta wave e poderão viver em arquivos dedicados por domínio sob `.studio/`;
5. o shell avança apenas quando `build`, `pack` e `manifest` reportarem sucesso.
A recomendação inicial desta agenda é:
1. fazer `Play` chamar explicitamente `build` e `pack`;
2. manter `build` e `pack` como operações domain-owned com logs e resultado binário de sucesso/falha nesta wave;
3. adiar o controle fino de drift/freshness para uma agenda própria posterior;
4. promover `build/` como artifact root runnable desta wave;
5. gerar `manifest.json` em `build/` sempre a partir do build corrente;
6. tratar o resultado de cada operação como contrato explícito para o `Play`, sem heurística oportunista baseada apenas em presença de arquivo.
## Resolution
Próximo passo sugerido: fechar uma decision de `studio` que trave o fluxo de preparação do `Play/Stop` com estas amarras normativas já explícitas:
1. `Play` é apenas o orquestrador de `build`, `pack` e `manifest`;
2. nesta wave, `build` sempre executa quando chamado pelo `Play`;
3. nesta wave, `pack` sempre executa quando chamado pelo `Play`, e só é chamado se `build` tiver sucesso;
4. o artifact root runnable desta wave é `build/`, não `cartridge/`;
5. `manifest.json` é sempre gerado deterministicamente em `build/`, a partir do build corrente, e não copiado por conveniência;
6. freshness e drift ficam fora do escopo desta wave e, quando tratados, usarão arquivos dedicados por domínio sob `.studio/`, como `asset-workspace.json` e `editor-workspace.json`;
7. `Play` só segue adiante quando as operações necessárias reportarem sucesso.
@@ -1,128 +0,0 @@
---
id: AGD-0024
ticket: studio-play-stop-cartridge-flow
title: Play/Stop integration agenda for runtime execution from build using project runtime setup
status: in_progress
created: 2026-04-06
resolved: 2026-04-06
decision: DEC-0021
tags: [studio, runtime, play-stop, build, process, project-setup]
---
## Pain
Mesmo depois que o Studio conseguir preparar `build/`, o botão `Play` continuará incompleto sem um contrato claro para executar o runtime configurado no projeto contra esse artifact root.
Hoje o caminho do runtime já existe em `.studio/setup.json` via `ProjectLocalStudioSetup.prometeuRuntimePath`, mas esse valor ainda não participa de nenhuma execução real no shell.
Sem essa definição, o `Play/Stop` corre o risco de virar:
- um botão que prepara `build/` mas não executa nada;
- ou um launcher improvisado, sem owner claro para processo, logs, lifecycle e falhas.
## Context
Domain owner: `studio`.
Subdomínios referenciados: `runtime`.
O Studio já carrega `ProjectLocalStudioSetup` na `StudioProjectSession`.
Portanto o runtime configurado por projeto já está disponível para consumo em runtime de aplicação.
Após a decisão `DEC-0020`, esta agenda passa a assumir explicitamente que:
- `Play` prepara `build/` como artifact root runnable;
- `manifest.json` é gerado em `build/`;
- não há `cartridge/` separado nesta wave.
O comando desejado pelo usuário é conceitualmente:
`runtime run build`
usando o runtime configurado no projeto atual.
Esta agenda não rediscute preparação de `build/`.
Ela assume a saída de `DEC-0020` como pré-condição e foca no segundo passo do `Play`: iniciar, observar e interromper o processo de runtime.
Também há um constraint de UX desta wave:
- ao apertar `Play`, o usuário deverá ser levado para o futuro `DebuggerWorkspace`, mesmo que essa surface ainda não esteja construída;
- até essa surface existir, os logs do runtime precisarão "ficar voando", isto é, viver provisoriamente fora do destino final pretendido;
- a etapa de `pack` usada por `Play` deve preservar seu ciclo de validação antes da execução do runtime;
- os logs de `build` e `pack` também devem convergir para o destino do debugger, porque é nessa surface que o usuário verá falhas de compilação, validação ou packing durante o fluxo do `Play`.
Também há um constraint de escopo nesta wave:
- checks adicionais de preflight antes do `build`, como arquivos do editor ainda não salvos, não entram agora;
- quando essa wave futura existir, ela deverá bloquear o `Play` antes do `build` com erro explícito, em vez de ser tratada como detalhe implícito de runtime.
## Open Questions
- [x] O `Play` deve falhar imediatamente quando `prometeuRuntimePath` estiver ausente, ou o shell deve oferecer algum repair path explícito antes de abortar?
- Resposta proposta: nesta wave, o `Play` deve falhar imediatamente com erro explícito quando `prometeuRuntimePath` estiver ausente, inválido, inexistente ou não executável; repair path guiado fica para uma wave posterior.
- [x] O Studio deve executar o runtime diretamente pelo binário configurado, ou por um wrapper/comando fixo resolvido a partir desse path?
- Resposta proposta: o Studio deve executar como processo externo o binário configurado em `ProjectLocalStudioSetup.prometeuRuntimePath`, apontando para `build/` e usando o subcomando `run` nesta wave; uma futura wave de debugger poderá trocar esse subcomando para `debug`.
- [x] O `Stop` deve encerrar apenas o processo de runtime ativo iniciado pelo shell atual, ou também limpar algum estado transitório adicional no Studio?
- Resposta proposta: `Stop` deve encerrar apenas o processo de runtime ativo iniciado pelo `Play` atual; não deve limpar estado transitório adicional além do lifecycle desse processo.
- [x] Onde os logs de stdout/stderr do runtime devem viver nesta primeira wave: activity feed, shipper logs, uma surface dedicada, ou combinação mínima dessas superfícies?
- Resposta proposta: o destino final dos logs deve ser o futuro `DebuggerWorkspace`, e o `Play` deve navegar para essa surface ao iniciar a execução; até ela existir, stdout/stderr e também os logs de `build`/`pack` ficam provisoriamente em uma solução transitória desacoplada, enquanto o Activity Feed recebe apenas eventos resumidos de início, sucesso de término e falha.
- [x] Como o shell deve serializar múltiplos cliques em `Play`: ignorar enquanto já está rodando, reiniciar, ou encadear stop + rerun?
- Resposta proposta: enquanto já houver runtime ativo iniciado pelo shell atual, cliques adicionais em `Play` devem ser ignorados até o processo sair ou o usuário apertar `Stop`.
- [x] O `pack` usado pelo `Play` pode empacotar diretamente, ou deve preservar o ciclo de validação antes da execução do runtime?
- Resposta proposta: o `pack` usado pelo `Play` deve preservar seu ciclo de validação antes da execução; se a validação bloquear o pack, o runtime não deve iniciar.
- [x] Checks extras antes do `build`, como arquivos não salvos no editor, entram nesta wave?
- Resposta proposta: não; preflight adicional de `build`, incluindo arquivos ainda não salvos, fica explicitamente para uma wave posterior e não altera o contrato desta agenda.
- [x] A execução da agenda 24 deve validar explicitamente a existência de `build/manifest.json` antes do spawn, ou isso fica implícito pelo sucesso da preparação?
- Resposta proposta: isso fica implícito pelo sucesso da preparação definida em `DEC-0020`; a agenda 24 não adiciona check redundante de existência de `manifest.json` antes do spawn.
## Options
### Option A - Play/Stop controla um processo único de runtime do projeto ativo
- **Approach:** O shell resolve o runtime configurado no `ProjectLocalStudioSetup`, executa diretamente o binário configurado contra `build/` como processo do projeto ativo, mantém handle desse processo e usa `Stop` para encerrar exatamente esse processo.
- **Pro:** O comportamento do botão fica simples, previsível e diretamente alinhado ao modelo visual de toggle.
- **Con:** Exige que o Studio introduza ownership explícito de processo, logs e cleanup, em vez de só alternar estado visual.
- **Maintainability:** Boa, porque o shell passa a ter um contrato único de execução por projeto e um lifecycle claro.
### Option B - Play delega a execução ao workspace ou a um launcher externo sem handle direto no shell
- **Approach:** O shell apenas dispara uma ação indireta e considera-se "running" sem possuir o processo como first-class state próprio.
- **Pro:** Menor acoplamento inicial entre shell e camada de processo.
- **Con:** O `Stop` fica semanticamente fraco ou enganoso, porque o shell não controla de verdade o processo que diz estar executando.
- **Maintainability:** Fraca, porque o toggle visual deixa de corresponder ao lifecycle real da execução.
## Discussion
O ponto mais importante desta agenda é alinhar o significado de `Stop`.
Se o shell não possui o processo de runtime como state explícito, o botão vira só uma fantasia visual.
Como o runtime path já é project-local setup carregado na sessão, o Studio já tem o owner certo para resolver o binário configurado.
O que falta é explicitar o contrato operacional:
1. validar que o runtime configurado existe e é executável;
2. executar `build`;
3. executar a validação de `pack`;
4. executar `pack` somente quando a validação permitir;
5. enviar os logs de `build` e `pack` para a surface de debugger/logs da execução;
6. rodar como processo externo o runtime configurado contra `build/` no contexto do projeto ativo, usando `run` nesta wave;
7. capturar stdout/stderr;
8. refletir running/stopped/failure no shell;
9. interromper o processo correto quando o usuário apertar `Stop`.
A execução do runtime nesta agenda confia no contrato de preparação anterior.
Portanto, esta wave não introduz preflight redundante para verificar novamente a existência de `build/manifest.json` antes do spawn.
A recomendação inicial desta agenda é:
1. fazer o shell ser owner de um único runtime-process handle por projeto ativo;
2. resolver o comando a partir de `ProjectLocalStudioSetup.prometeuRuntimePath`;
3. falhar de forma explícita quando o runtime do projeto estiver ausente ou inválido;
4. definir `Stop` como término do processo iniciado pelo `Play` atual, e não como reset genérico de UI;
5. ignorar novo `Play` enquanto o processo atual ainda estiver rodando;
6. preservar a validação de pack antes do pack efetivo na preparação do `Play`;
7. tratar o futuro `DebuggerWorkspace` como destino canônico da execução e dos logs de runtime, `build` e `pack`;
8. enquanto o `DebuggerWorkspace` não existir, manter stdout/stderr e logs de preparação em uma solução transitória, usando o Activity Feed apenas para sinais resumidos de lifecycle;
9. deixar checks extras de preflight antes do `build`, como arquivos não salvos, fora desta wave;
10. fixar `run` como o subcomando de execução desta wave, deixando `debug` para uma futura wave de debugger;
11. confiar no sucesso da preparação anterior sem adicionar preflight redundante de `manifest.json` antes do spawn.
## Resolution
Próximo passo sugerido: fechar uma decision de `studio` que defina ownership de processo para `Play/Stop`, preserve o ciclo de validação + pack antes da execução do runtime, fixe a execução como processo externo do runtime configurado usando `run` contra `build/`, trate o `DebuggerWorkspace` como destino futuro da sessão de execução e explicite que checks extras de preflight do `build` ficam para uma wave posterior.