prometeu-studio/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0009	studio-debugger-workspace-integration	Integrar ../debugger ao Studio como workspace dedicado	in_progress	2026-03-30	2026-04-06	DEC-0022	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

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