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