diff --git a/discussion/index.ndjson b/discussion/index.ndjson index e8c14c56..66dc07bf 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -7,7 +7,7 @@ {"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} -{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-06","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"in_progress","created_at":"2026-03-30","updated_at":"2026-04-06"}],"decisions":[{"id":"DEC-0022","file":"DEC-0022-studio-debug-workspace-native-integration.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0009"}],"plans":[{"id":"PLN-0043","file":"PLN-0043-debug-workspace-first-wave-surface.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0022"]},{"id":"PLN-0044","file":"PLN-0044-runtime-handshake-selective-integration.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0021","DEC-0022"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} {"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]} {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} {"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]} @@ -20,4 +20,4 @@ {"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]} {"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]} {"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]} -{"type":"discussion","id":"DSC-0022","status":"open","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-06","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[{"id":"AGD-0023","file":"AGD-0023-studio-play-stop-shipper-phase-1.md","status":"in_progress","created_at":"2026-04-06","updated_at":"2026-04-06"},{"id":"AGD-0024","file":"AGD-0024-studio-play-stop-runtime-run-cartridge.md","status":"in_progress","created_at":"2026-04-06","updated_at":"2026-04-06"}],"decisions":[{"id":"DEC-0020","file":"DEC-0020-studio-play-stop-build-pack-preparation.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0023"},{"id":"DEC-0021","file":"DEC-0021-studio-play-stop-runtime-run-from-build.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0041","file":"PLN-0041-shipper-preparation-foundation.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020"]},{"id":"PLN-0042","file":"PLN-0042-shared-execution-session-and-log-contracts.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020","DEC-0021","DEC-0022"]},{"id":"PLN-0045","file":"PLN-0045-play-stop-end-to-end-execution-flow.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020","DEC-0021","DEC-0022"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} diff --git a/discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md b/discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md new file mode 100644 index 00000000..cd73bdad --- /dev/null +++ b/discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md @@ -0,0 +1,56 @@ +--- +id: LSN-0022 +ticket: studio-play-stop-cartridge-flow +title: Studio Play/Stop and Debugger Workspace Integration +status: done +created: 2026-04-07 +tags: [studio, play-stop, debugger, runtime, shipper] +--- + +## Summary + +This lesson covers the implementation of the first wave of the `Play/Stop` flow in Studio and its integration with a native `DebugWorkspace`. + +The feature enables developers to: +- Press `Play` to build, pack, and run the current project in the configured runtime. +- Automatically navigate to a `DebugWorkspace` that shows merged preparation and runtime logs. +- Press `Stop` to kill the active runtime process. + +## Key Decisions + +Based on `DEC-0020`, `DEC-0021`, and `DEC-0022`: + +1. **Preparation Pipeline**: The `Play` flow orchestrates existing domain operations: `build` -> `validate pack` -> `pack` -> `manifest generation`. All artifacts are kept in `build/`, avoiding a redundant `cartridge/` directory for this wave. +2. **Runtime Command**: The runtime is executed externally as `"" run build` with the project root as its working directory. +3. **Process Ownership**: Studio owns exactly one active runtime process handle per project shell. +4. **Merged Logs**: Preparation logs (build, pack validation, pack) and runtime logs (stdout/stderr) are merged into a single execution-session stream. +5. **Native Debugger Workspace**: A native `DebugWorkspace` hosts the execution session and acts as the primary log sink. It is not an external launcher but a real Studio workspace. +6. **Shared Session State**: The execution state (`idle`, `preparing`, `connecting`, `running`, etc.) lives outside the visual workspace lifecycle in a shared `StudioExecutionSessionService`. + +## Implementation Details + +### `StudioPlayStopCoordinator` +The main orchestrator for the `Play` and `Stop` actions. It: +- Manages the `preparing` -> `connecting` -> `running` state machine. +- Invokes the `StudioShipperService` for preparation. +- Spawns the external runtime process using `StudioExternalRuntimeProcessLauncher`. +- Merges log streams from both preparation and runtime into the `StudioExecutionSessionService`. + +### `DebugWorkspace` +A Studio `Workspace` implementation that reflects the `StudioExecutionSnapshot`. It uses `DebugWorkspaceProjection` to transform the session logs into a display-ready format. + +### `StudioShipperService` +Aggregates the domain-specific tasks (compiler build, packer pack) and generates the mandatory `manifest.json` in the `build/` directory. + +## Common Pitfalls & Anti-Patterns + +- **Redundant Checks**: Do not add manual `manifest.json` existence checks before spawning. The success of the preparation pipeline already guarantees its presence according to the contract. +- **State Duplication**: Avoid tracking execution state in both the shell and the workspace. The shared `StudioExecutionSessionService` is the single source of truth. +- **Technical Linkage**: Do not hard-link the Studio codebase with the legacy `../debugger` repository. Selective migration of protocol/session logic is preferred. + +## References + +- `DEC-0020`: Build and pack preparation. +- `DEC-0021`: External runtime execution. +- `DEC-0022`: Native `DebugWorkspace` integration. +- `PLN-0045`: End-to-end execution flow. diff --git a/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md b/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md deleted file mode 100644 index 5045a146..00000000 --- a/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md +++ /dev/null @@ -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 `"" 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. diff --git a/discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md b/discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md deleted file mode 100644 index 05ccfa8b..00000000 --- a/discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md b/discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md deleted file mode 100644 index aa1a0358..00000000 --- a/discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md b/discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md deleted file mode 100644 index 58639240..00000000 --- a/discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: DEC-0020 -ticket: studio-play-stop-cartridge-flow -title: Decision for Play/Stop build and pack preparation through build-owned artifacts -status: accepted -created: 2026-04-06 -accepted: 2026-04-06 -agenda: AGD-0023 -plans: [PLN-0041, PLN-0042, PLN-0045] -tags: [studio, play-stop, build, pack, compiler, packer, manifest, shell] ---- - -## Decision - -Domain owner: `studio`. -Referenced subdomains: `compiler`, `packer`, `runtime`. - -The Studio `Play` flow for this wave SHALL be implemented as an orchestration over existing domain operations, not as a separate shipping pipeline. - -The decision is: - -1. `Play` MUST call `build` first. -2. `pack` MUST run only after `build` completes successfully. -3. `Play` MUST treat `build/` as the runnable artifact root for this wave. -4. `Play` MUST NOT materialize or depend on a separate `cartridge/` directory in this wave. -5. `manifest.json` MUST be generated deterministically into `build/` from the current build result and project-owned metadata. -6. `Play` MUST only need to evaluate whether each required operation succeeded or failed. -7. Detailed operation logs MUST remain available alongside the operation results consumed by `Play`. -8. The Studio shipper service MUST own preparation orchestration and preparation-log aggregation for this wave. -9. Preparation logs MUST preserve at least the distinct channels `build`, `pack-validation`, and `pack`. -10. Drift/freshness reuse logic is explicitly out of scope for this wave. -11. A future drift/freshness wave MUST use domain-specific `.studio/` files rather than the main session-restoration snapshot. - -## Rationale - -This decision intentionally keeps the first executable `Play` wave narrow. - -The repository already shows: - -- compiler ownership of `build/program.pbx`, -- packer ownership of `build/assets.pa` and companion build artifacts, -- and no accepted requirement that a separate `cartridge/` assembly step must exist before runtime execution. - -Creating a new shipper/materialization layer now would add an extra boundary before the base `Play` integration exists. -Likewise, pushing drift/freshness inference into `Play` would make the shell the owner of compiler and packer validity rules, which is the wrong boundary. - -This decision therefore chooses the smallest correct operational split: - -- `Play` orchestrates, -- `shipper` owns preparation orchestration and preparation-log aggregation, -- `build` produces compiler artifacts, -- `pack` produces packer artifacts, -- `manifest` is generated after successful preparation, -- and runtime execution in the next wave may consume `build/` directly. - -## Technical Specification - -### 1. Orchestration Order - -The `Play` preparation path MUST execute in this order: - -1. `build` -2. `pack` (only if `build` succeeded) -3. `manifest` generation in `build/` -4. handoff to the runtime-execution flow covered by a separate agenda/decision wave - -`Play` MUST stop immediately on the first failed required step. -No cancellation of the preparation phase is defined in this wave. - -### 2. Artifact Root - -For this wave, `build/` is the canonical runnable artifact root. - -At minimum, the prepared runtime-facing output in `build/` SHALL include: - -- `program.pbx` -- `assets.pa` -- `manifest.json` - -Packer companion artifacts may remain in `build/` as domain-owned outputs. -They do not redefine the minimum contract required by `Play`. - -### 3. Result Contract - -The result contract consumed by `Play` for this wave MUST be binary at the control-flow level: - -- `success` -- `failed` - -`Play` MUST NOT need to interpret finer-grained reuse or freshness states in this wave. -Operational logs from `build`, `pack`, and manifest generation MUST remain available so the shell can surface useful diagnostics without owning domain-specific decision logic. -For this wave, those preparation logs are owned and aggregated by the Studio shipper service. - -### 4. Manifest Generation - -`manifest.json` MUST NOT be copied opportunistically from an older location. - -Instead, it MUST be generated on every successful preparation run: - -- in `build/`, -- from the current build result, -- and from project-owned metadata required by the runtime-facing manifest contract. - -### 5. Drift and Freshness Deferral - -This decision does not authorize a freshness-based skip path yet. - -Rules: - -- `Play` MUST NOT infer artifact validity from file presence alone. -- This wave MAY always execute `build` and `pack` when `Play` is pressed. -- If a later wave introduces drift/freshness control, that logic MUST be discussed separately before implementation. -- That later wave MUST keep operational metadata in dedicated domain files under `.studio/`, with the agreed initial direction being `asset-workspace.json` and `editor-workspace.json`. -- That later wave MUST NOT mix such metadata into `.studio/state.json` by convenience. - -### 6. Boundary With Existing Workspaces - -The current `ShipperWorkspace` scratch implementation does not become the normative backend for `Play` by inertia. - -This decision does not require: - -- a new shipping module, -- a separate cartridge-materialization directory, -- or Play-owned drift heuristics. - -Existing workspaces may remain useful as manual or diagnostic surfaces, but they MUST NOT redefine the `Play` preparation contract established here. - -### 7. Preparation Logging Boundary - -For this wave, preparation logging MUST follow these rules: - -- build and pack remain owners of their own log production; -- the Studio shipper service aggregates preparation output for user-facing consumption; -- the aggregated preparation stream MUST preserve distinct source channels for `build`, `pack-validation`, and `pack`; -- downstream debugger/execution surfaces consume that aggregated preparation output rather than redefining preparation ownership. - -## Constraints - -1. This decision covers preparation only, not runtime process ownership or `Stop` behavior. -2. This decision does not yet define the exact manifest field mapping beyond deterministic generation from current build inputs and project metadata. -3. This decision does not yet define a drift fingerprint model. -4. Any later attempt to skip `build` or `pack` based on freshness requires a new discussion wave or explicit revision of this decision. -5. Any later reintroduction of `cartridge/` as a mandatory runtime root requires a new decision or explicit revision of this one. - -## Revision Log - -- 2026-04-06: Initial draft from AGD-0023. diff --git a/discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md b/discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md deleted file mode 100644 index 267bbbe9..00000000 --- a/discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -id: DEC-0021 -ticket: studio-play-stop-cartridge-flow -title: Decision for Play/Stop runtime execution from build through external run process -status: accepted -created: 2026-04-06 -accepted: 2026-04-06 -agenda: AGD-0024 -plans: [PLN-0042, PLN-0044, PLN-0045] -tags: [studio, runtime, play-stop, build, process, debugger, project-setup, logs] ---- - -## Decision - -Domain owner: `studio`. -Referenced subdomains: `runtime`. - -This decision defines the runtime-execution contract that follows the preparation contract already described in `DEC-0020`. - -The decision is: - -1. `Play` MUST execute the configured runtime as an external process. -2. The runtime executable path MUST come from `ProjectLocalStudioSetup.prometeuRuntimePath`. -3. The external command for this wave MUST be exactly `"" run build`. -4. The process MUST run with the project root as its current working directory. -5. `Play` MUST rely on the successful completion of the preparation pipeline and MUST NOT add a redundant manifest-existence preflight in this wave. -6. `Play` MUST fail explicitly when the configured runtime path is missing, invalid, nonexistent, non-executable, or cannot be spawned. -7. `Play` MUST own exactly one active runtime-process handle for the current project shell. -8. While that process is active, additional `Play` actions MUST be ignored. -9. `Stop` in this wave MUST kill the active runtime process directly. -10. The future `DebuggerWorkspace` SHALL be the canonical destination of execution and logs. -11. Until that workspace exists, runtime logs and shipper-provided preparation logs MUST flow to a temporary surface, while the Activity Feed only receives summarized lifecycle events. -12. The shipper service remains the owner of preparation orchestration and aggregated preparation output. -13. The `pack` step used by `Play` MUST preserve validation before packing, and runtime execution MUST NOT start if validation blocks the pack. -14. Additional pre-build editor preflight checks, including unsaved-file detection, are explicitly deferred to a future wave. -15. No cancellation of the preparation phase is supported in this wave. -16. The future debugger wave MAY replace `run` with `debug`, but that is not authorized by this decision. - -## Rationale - -`Play/Stop` only becomes semantically real if the shell owns the runtime process it claims to start and stop. - -After `DEC-0020`, the runnable artifact root for this wave is `build/`, and the preparation flow already owns generation of `manifest.json`. -This means the runtime-execution wave does not need another packaging boundary and does not need redundant manifest-existence checks before spawn. - -The narrowest correct contract is therefore: - -- prepare through `build -> validate pack -> pack -> manifest`, -- treat shipper as the owner of preparation output and aggregated preparation logs, -- spawn the configured runtime externally with `run build`, -- keep a single process handle, -- and surface logs in the future debugger destination. - -This keeps responsibility boundaries clear: - -- preparation remains owned by the earlier preparation decision, -- runtime-process ownership belongs to the shell, -- and future debugger behavior remains a later wave rather than being guessed now. - -## Technical Specification - -### 1. Runtime Command - -For this wave, the Studio shell MUST construct and execute the runtime command as: - -`"" run build` - -Rules: - -- `runtimePath` MUST be read from `ProjectLocalStudioSetup.prometeuRuntimePath`; -- the process MUST execute with `cwd` equal to the project root; -- no wrapper command is introduced in this wave; -- no `debug` subcommand is introduced in this wave. - -### 2. Execution Order - -`Play` preparation and execution MUST follow this order: - -1. `build` -2. `pack` validation -3. `pack` only if validation allows it -4. runtime spawn with `run build` - -The shell MUST stop on first failure. -If `build` fails, no pack validation, pack, or runtime spawn occurs. -If pack validation blocks, no pack or runtime spawn occurs. -If pack fails, runtime spawn does not occur. -If preparation fails, no cancellation path is offered in this wave; the flow simply terminates in failure. - -### 3. Preparation Contract Reliance - -This decision depends on `DEC-0020`. - -Rules: - -- the shell MUST rely on the success of the earlier preparation pipeline; -- the shell MUST NOT add a redundant check for `build/manifest.json` existence before spawn in this wave; -- a missing manifest after successful preparation is a violation of the earlier preparation contract, not a new runtime-execution rule. - -### 4. Runtime Preflight - -Before spawning the external process, the shell MUST treat the following conditions as explicit preflight failures: - -- missing `prometeuRuntimePath`, -- blank `prometeuRuntimePath`, -- nonexistent runtime path, -- non-executable runtime path, -- spawn failure. - -This wave does not yet define a broader runtime repair flow. - -### 5. Process Ownership and Stop Semantics - -The shell MUST own exactly one active runtime-process handle per active project shell. - -Rules: - -- `Play` while the process is active MUST be ignored; -- `Stop` MUST target only the process started by the current `Play` flow; -- `Stop` in this wave MUST kill that process directly; -- `Stop` has no effect during `preparing` because preparation cancellation is not defined in this wave; -- graceful debugger-oriented stop commands are deferred to a future debugger wave. - -### 6. Logging and Debugger Destination - -The canonical destination for execution-session logs SHALL be the future `DebuggerWorkspace`. - -For this wave: - -- the shell MUST navigate toward that execution destination when `Play` starts, before runtime spawn is attempted; -- logs from `build`, pack validation, `pack`, and runtime stdout/stderr MUST converge on that execution-log destination; -- preparation logs arrive there through shipper-owned aggregated output; -- until the `DebuggerWorkspace` exists, those logs MUST use a temporary/transitional surface; -- the Activity Feed MUST remain a summary surface and MUST NOT become the primary full-log destination. - -### 7. Shared Session State - -The Studio shell and debugger destination require shared execution state that exists independently of the visual lifecycle of the workspace. - -For this wave, the minimum state machine SHALL distinguish at least: - -- `idle` -- `preparing` -- `prepare_failed` -- `connecting` -- `running` -- `runtime_failed` -- `stopped` - -This state is not owned solely by the visual workspace. - -### 8. Deferred Checks - -This decision explicitly defers: - -- unsaved-editor-file checks before `build`, -- broader build preflight policy, -- graceful runtime stop commands, -- debugger-specific execution semantics, -- and any redundant manifest-presence preflight beyond the contract already owned by `DEC-0020`. - -When introduced later, those concerns MUST be handled in a separate discussion wave or explicit revision. - -## Constraints - -1. This decision covers external runtime execution through `run`, not debugger execution through `debug`. -2. This decision assumes the preparation contract of `DEC-0020` without reopening it. -3. This decision does not yet define the concrete temporary UI surface that will host execution logs before the `DebuggerWorkspace` exists. -4. This decision does not yet define richer exit-code UX beyond success/failure lifecycle handling. -5. This decision does not yet define restart semantics beyond ignoring repeated `Play` while active. - -## Revision Log - -- 2026-04-06: Initial draft from AGD-0024. diff --git a/discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md b/discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md deleted file mode 100644 index 8d6cdddd..00000000 --- a/discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -id: DEC-0022 -ticket: studio-debugger-workspace-integration -title: Decision for native Studio DebugWorkspace integration with selective debugger migration -status: accepted -created: 2026-04-06 -accepted: 2026-04-06 -agenda: AGD-0009 -plans: [PLN-0042, PLN-0043, PLN-0044, PLN-0045] -tags: [studio, debugger, workspace, integration, logs, runtime, play-stop] ---- - -## Decision - -Domain owner: `studio`. -Cross-domain reference: sibling repo `../debugger`. -Normative upstream dependencies: `DEC-0020`, `DEC-0021`. - -This decision defines the first integration wave of `DebugWorkspace` inside Studio. - -The decision is: - -1. `Debug` in Studio MUST become a real native workspace, not an external launcher. -2. This integration MUST remain compatible with `DEC-0020` and `DEC-0021` and MUST NOT reinterpret preparation or execution contracts by inference. -3. The first wave of `DebugWorkspace` MUST focus on two capabilities only: - - runtime/debug-session handshake sufficient for the current `Play/Stop` flow, - - and merged execution-log sinking for preparation and runtime. -4. The first wave does NOT need to be perfect. A simple but functional session state and log sink is sufficient. -5. The `../debugger` repository MUST be treated as architectural reference and selective source of useful details, not as a dependency to be linked or a codebase to be copied wholesale. -6. Studio MUST NOT create a technical linkage between the two projects for this wave. -7. Copying code from `../debugger` MUST be avoided by default, but MAY be done selectively when concretely useful. -8. The correct integration boundary is in useful session/protocol/remote-debug policy details, not in `Application`/`Stage` bootstrap or standalone UI hosting. -9. `Play/Stop` MUST continue owning connect/attach/disconnect behavior under the hood in this wave. -10. `DebugWorkspace` MUST consume shipper-provided aggregated preparation logs and runtime logs through a shared session/service boundary. -11. `DebugWorkspace` MUST be the destination for merged logs from `build`, pack validation, `pack`, and runtime execution. -12. Build and pack remain owners of their own logs, but the user-facing execution surface MUST show those logs merged in the debugger destination. -13. The global Activity Feed MUST remain a summary surface rather than the primary raw-log destination. -14. The first wave MUST exclude profiler-specific behavior. -15. The standalone `../debugger` MUST NOT be evolved as part of this Studio integration and is expected to be removed once Studio becomes mature enough to replace it. - -## Rationale - -Recent `Play/Stop` decisions made `DebugWorkspace` no longer speculative. - -`DEC-0021` already establishes that: - -- `Play` navigates toward the future debugger destination, -- build, pack-validation, pack, and runtime logs converge there, -- and `Play/Stop` owns the current run-process contract. - -That means the immediate job of agenda 9 is not to design the final debugger product. -Its immediate job is to provide the native Studio surface that can host: - -- session state, -- handshake with the runtime, -- and a merged sink for execution-related logs. - -The existing `../debugger` still matters, but mostly as a source of tested ideas and useful protocol/session details. -Treating it as a live dependency would be the wrong topological move because: - -- the Studio is intended to become the durable host, -- the sibling debugger will be removed later, -- and hard-linking the repositories now would increase migration cost for little value. - -The narrowest correct answer is therefore: - -- native `DebugWorkspace` in Studio, -- selective migration only, -- no direct project linkage, -- a shared session/service boundary outside the visual workspace, -- no profiler in the first cut, -- and enough runtime handshake + log sinking to support the already-decided `Play/Stop` flow. - -## Technical Specification - -### 1. Upstream Contract Boundaries - -This decision is downstream of `DEC-0020` and `DEC-0021`. - -Rules: - -- `DEC-0020` remains authoritative for preparation through `build -> validate pack -> pack -> manifest`; -- `DEC-0021` remains authoritative for runtime execution through external `"" run build` and current `Play/Stop` process ownership; -- this decision MUST NOT redefine those flows; -- any attempt to change preparation or execution semantics requires explicit revision of the upstream decisions rather than reinterpretation here. - -### 2. First-Wave Scope - -The first-wave `DebugWorkspace` MUST provide: - -- a native Studio workspace surface, -- basic debug/run session state, -- handshake behavior with the runtime sufficient for the current flow, -- and a merged log sink for execution-related activity. - -The first wave MAY be visually simple. -It does not need polished debugger UX yet. - -### 3. Session and Handshake - -The workspace MUST expose enough session state to show at least: - -- connecting, -- connected, -- failed, -- and equivalent stopped/disconnected state as needed by the current flow. - -Handshake details MAY be derived from `../debugger` where useful, but MUST be integrated into Studio-native session/workspace boundaries. - -For this wave: - -- `Play/Stop` remains the owner of under-the-hood connect/attach/disconnect behavior; -- `DebugWorkspace` is the native surface that reflects and hosts that session; -- the underlying session state MUST exist outside the visual workspace lifecycle so the Studio shell can react to it globally. - -### 4. Logging - -The `DebugWorkspace` MUST be the merged sink destination for: - -- `build` logs, -- pack-validation logs, -- `pack` logs, -- runtime stdout/stderr. - -Rules: - -- build and pack keep ownership of their own log production; -- shipper owns the aggregation of preparation logs for user-facing consumption; -- the debugger destination consumes merged preparation output plus runtime logs; -- the initial merged sink MAY be a simple console/list with visible source/origin labels; -- source/origin labels MUST preserve at least `build`, `pack-validation`, `pack`, and `runtime`; -- the merged sink does not need sophisticated structure in the first wave; -- the Activity Feed MUST only carry summarized lifecycle signals. - -### 5. Shared Session State - -The first-wave debugger integration MUST consume a shared session/service boundary that is not owned solely by the visual workspace. - -At minimum, that shared state MUST distinguish: - -- `idle` -- `preparing` -- `prepare_failed` -- `connecting` -- `running` -- `runtime_failed` -- `stopped` - -The `DebugWorkspace` consumes and reflects this state. - -### 6. Integration Topology - -The integration topology for this wave MUST be selective migration into Studio. - -Rules: - -- no composite build or equivalent live technical linkage with `../debugger`; -- no requirement to keep the standalone debugger as a parallel supported surface; -- no wholesale copy by inertia; -- selective code migration is allowed when concretely useful. - -The intended direction is: - -- Studio becomes the durable host, -- `../debugger` is not extended further for this effort, -- and the sibling project may be removed once Studio matures enough. - -### 7. Native Studio Shape - -`DebugWorkspace` MUST obey native Studio workspace rules for: - -- lifecycle, -- event-bus integration, -- theming, -- i18n, -- navigation under the Studio shell. - -This decision does not authorize embedding the standalone debugger bootstrap as the main integration unit. - -### 8. Explicit Exclusions - -This decision does not yet define: - -- profiler integration, -- polished final debugger UX, -- a rich manual connect/disconnect control surface, -- a final structured logging model, -- cancellation of preparation, -- or any change from `run` to `debug` in the runtime command path. - -Those concerns remain future waves. - -## Constraints - -1. This decision is subordinate to `DEC-0020` and `DEC-0021`. -2. This decision defines the first wave of `DebugWorkspace`, not the complete debugger product. -3. This decision assumes selective use of `../debugger` knowledge/details without creating a permanent dependency. -4. This decision does not authorize profiler behavior. -5. This decision does not authorize changing current `Play/Stop` ownership semantics. - -## Revision Log - -- 2026-04-06: Initial draft from AGD-0009. diff --git a/discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md b/discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md deleted file mode 100644 index e48f5160..00000000 --- a/discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -id: PLN-0041 -ticket: studio-play-stop-cartridge-flow -title: Ordered Plan 1 - Shipper preparation foundation for build, pack, and manifest -status: review -created: 2026-04-06 -completed: -tags: [studio, play-stop, shipper, build, pack, manifest] ---- - -## Objective - -Implement the Studio shipper service as the owner of preparation orchestration for `build -> pack-validation -> pack -> manifest`, with deterministic output in `build/`. - -## Background - -`DEC-0020` establishes that preparation is Studio-owned, that `build/` is the runnable artifact root, and that shipper owns preparation orchestration plus aggregation of preparation logs. - -This is the first and foundational plan in the family. Later plans depend on its service boundary and result contracts. - -## Scope - -### Included -- Introduce or reshape a Studio-owned shipper service boundary. -- Execute `build`, pack validation, `pack`, and manifest generation in the required order. -- Produce deterministic preparation results and failure boundaries. -- Preserve preparation log channels `build`, `pack-validation`, and `pack`. - -### Excluded -- External runtime spawning. -- Debugger workspace UI. -- Runtime handshake. -- Drift/freshness reuse logic. - -## Execution Steps - -### Step 1 - Define the shipper service contract - -**What:** Add a Studio-owned service/API for preparation that exposes ordered preparation, result status, and preparation-log output. -**How:** Introduce dedicated types for preparation request/result and channel-aware preparation log entries. Keep the service independent from UI controls and workspaces. -**File(s):** `prometeu-studio/src/main/java/p/studio/.../shipper/*` (new package), existing `ShipperWorkspace` call sites as adapters only. - -### Step 2 - Implement ordered preparation - -**What:** Execute compiler build, pack validation, pack, and manifest generation through the shipper service. -**How:** Reuse existing compiler and packer entrypoints. Enforce stop-on-first-failure. Do not introduce cancellation. Ensure pack validation blocks pack when needed. -**File(s):** `prometeu-studio` service layer, packer integration call sites, manifest generation implementation. - -### Step 3 - Materialize the deterministic build contract - -**What:** Ensure successful preparation leaves `build/program.pbx`, `build/assets.pa`, and `build/manifest.json` in the expected state. -**How:** Keep compiler and packer domain ownership of their artifacts, but make manifest generation part of shipper success. Preserve the absence of a separate `cartridge/` root. -**File(s):** shipper implementation, manifest-generation code, any preparation DTOs/results. - -### Step 4 - Publish channel-preserving preparation output - -**What:** Aggregate preparation output for downstream consumption while preserving per-channel identity. -**How:** Build a merged-but-structured stream that labels entries as `build`, `pack-validation`, or `pack`. Expose it as shipper-owned output rather than UI-owned state. -**File(s):** shipper service/result/log types, adapters from compiler and packer logs. - -## Test Requirements - -### Unit Tests -- Verify shipper enforces the exact order `build -> pack-validation -> pack -> manifest`. -- Verify pack validation failure stops the flow before pack. -- Verify manifest generation only happens after successful build and pack. -- Verify aggregated preparation logs preserve the three required source channels. - -### Integration Tests -- Exercise a successful preparation flow against a real project fixture and assert expected files exist in `build/`. -- Exercise build failure and assert pack and manifest are skipped. -- Exercise pack-validation failure and assert pack and manifest are skipped. - -### Manual Verification -- Trigger shipper preparation on a real Studio project and confirm `build/` contains the expected artifacts. -- Inspect emitted preparation logs and confirm channel labels remain visible. - -## Acceptance Criteria - -- [ ] A Studio-owned shipper service exists and is the sole owner of preparation orchestration. -- [ ] Preparation executes in the exact decision-ordered sequence. -- [ ] Preparation stops on first failure and does not support cancellation in this wave. -- [ ] Successful preparation leaves the required runnable files in `build/`. -- [ ] Preparation output preserves `build`, `pack-validation`, and `pack` channel identity. - -## Dependencies - -- Accepted `DEC-0020`. -- Existing compiler `build` entrypoint. -- Existing packer validation and pack entrypoints. - -## Risks - -- Hidden coupling to the current `ShipperWorkspace` scratch path may leak UI assumptions into the service boundary. -- Manifest generation may become entangled with runtime policy if not kept narrow. -- Log aggregation may collapse source identity if implemented as raw text concatenation. diff --git a/discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md b/discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md deleted file mode 100644 index 6216c062..00000000 --- a/discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -id: PLN-0042 -ticket: studio-play-stop-cartridge-flow -title: Ordered Plan 2 - Shared execution session and merged log contracts -status: review -created: 2026-04-06 -completed: -tags: [studio, play-stop, debugger, session, logs, state] ---- - -## Objective - -Define and implement the shared execution-session boundary that exists outside visual workspace lifecycle and carries state plus merged log contracts for preparation and runtime. - -## Background - -`DEC-0021` and `DEC-0022` require a shared state machine and a merged log destination independent of the visual `DebugWorkspace`. `DEC-0020` requires shipper-owned preparation log aggregation. - -This plan is intentionally cross-cutting and must land before the final orchestration and workspace consumption plans. - -## Scope - -### Included -- Shared session/service boundary outside the visual workspace. -- Minimum shared state machine: `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, `stopped`. -- Structured merged log-entry contract with visible source identity. -- Adapters for shipper-owned preparation output and runtime output to feed the shared session. - -### Excluded -- Final debugger workspace UI. -- Runtime process spawning details. -- Full handshake implementation details. -- Profiler behavior. - -## Execution Steps - -### Step 1 - Define shared state and session contracts - -**What:** Introduce shared types and services for execution-session state. -**How:** Create a Studio-owned session/service API not tied to `Workspace` lifecycle. Add explicit transitions for the minimum required states. -**File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent shared execution package. - -### Step 2 - Define merged log-entry contracts - -**What:** Add a structured log-entry model for merged execution logs. -**How:** Require at least `source`, `message`, `severity`, and ordering metadata such as timestamp/sequence. Preserve the source channels `build`, `pack-validation`, `pack`, and `runtime`. -**File(s):** shared execution/debug model package, service interfaces, DTOs/events. - -### Step 3 - Connect shipper output to the shared session - -**What:** Feed shipper-owned preparation output into the shared session boundary. -**How:** Adapt the shipper result/log stream into session log entries and preparation state transitions without moving ownership away from shipper. -**File(s):** shipper adapters, shared session service, orchestration glue. - -### Step 4 - Connect runtime output to the shared session - -**What:** Reserve the runtime side of the merged stream and state transitions for later orchestration plans. -**How:** Define append/update APIs now so later runtime plans can publish `connecting`, `running`, `runtime_failed`, and `stopped` without changing the contract shape. -**File(s):** shared session/service types and tests. - -## Test Requirements - -### Unit Tests -- Verify legal state transitions for the minimum state machine. -- Verify merged log entries preserve source identity and ordering metadata. -- Verify shipper output can be appended without collapsing channels. - -### Integration Tests -- Feed a simulated preparation success/failure sequence into the shared session and assert resulting state and log stream. -- Verify the shared session survives workspace recreation or absence. - -### Manual Verification -- Inspect a development build and confirm execution state remains available even if the visual debug surface is not yet mounted. - -## Acceptance Criteria - -- [ ] A shared execution-session service exists outside the visual workspace lifecycle. -- [ ] The minimum state machine is explicitly implemented. -- [ ] Merged log entries preserve source identity for `build`, `pack-validation`, `pack`, and `runtime`. -- [ ] Shipper preparation output can flow into the shared session without changing shipper ownership. - -## Dependencies - -- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`. -- `PLN-0041` shipper preparation foundation. - -## Risks - -- State transitions may become duplicated between shell, workspace, and service if ownership is not kept strict. -- Log models that are too thin will force churn once the debugger surface exists. -- Overdesign here could slow down the simple first wave the decisions explicitly allow. diff --git a/discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md b/discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md deleted file mode 100644 index af5fef3e..00000000 --- a/discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -id: PLN-0043 -ticket: studio-debugger-workspace-integration -title: Ordered Plan 3 - First-wave DebugWorkspace registration and temporary execution surface -status: review -created: 2026-04-06 -completed: -tags: [studio, debugger, workspace, logs, shell] ---- - -## Objective - -Register a native `DebugWorkspace` in Studio and provide a first-wave temporary execution surface that consumes shared session state and merged logs. - -## Background - -`DEC-0022` requires a real native workspace, not an external launcher. `DEC-0021` requires `Play` to navigate toward the debugger destination at the start of execution. - -This plan intentionally keeps the UI crude and execution-focused. - -## Scope - -### Included -- Register a concrete `DebugWorkspace` in the Studio shell. -- Consume the shared session/service boundary from `PLN-0042`. -- Render simple session state and a simple merged log sink with visible source labels. -- Provide a temporary but native in-Studio execution destination. - -### Excluded -- Polished final debugger UX. -- Rich manual connect/disconnect controls. -- Profiler behavior. -- Standalone debugger bootstrap embedding. - -## Execution Steps - -### Step 1 - Register the workspace in the shell - -**What:** Make `WorkspaceId.DEBUG` point to a real workspace implementation. -**How:** Add and register a native `DebugWorkspace` that follows Studio workspace lifecycle and event-bus rules. -**File(s):** `prometeu-studio/src/main/java/p/studio/window/MainView.java`, `prometeu-studio/src/main/java/p/studio/workspaces/.../DebugWorkspace.java` (new). - -### Step 2 - Add first-wave session state presentation - -**What:** Surface the shared session states in the workspace. -**How:** Render a simple status area or equivalent control showing at least `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, and `stopped`. -**File(s):** `DebugWorkspace` controls and supporting view models/bindings. - -### Step 3 - Add the temporary merged log sink - -**What:** Show merged execution logs in a simple native Studio surface. -**How:** Use a list/console style control with visible source labels and lightweight severity treatment. Consume the shared session log stream from `PLN-0042`. -**File(s):** `DebugWorkspace` controls, log pane/control package. - -### Step 4 - Preserve native Studio shape - -**What:** Keep lifecycle, theming, i18n, and shell-navigation compliance. -**How:** Avoid importing the standalone debugger host/bootstrap. Use only Studio-native workspace composition. -**File(s):** workspace implementation, i18n keys, theme/style files as needed. - -## Test Requirements - -### Unit Tests -- Verify the workspace can consume session state updates and reflect them. -- Verify merged log entries render with visible source identity. - -### Integration Tests -- Mount the workspace in a shell test and confirm it registers without throwing. -- Feed synthetic session/log events and confirm the workspace updates without owning the underlying state. - -### Manual Verification -- Open the `Debug` workspace from the Studio shell. -- Confirm session states and merged logs are visible in a simple but usable surface. - -## Acceptance Criteria - -- [ ] `WorkspaceId.DEBUG` resolves to a real native workspace. -- [ ] The workspace shows shared execution state. -- [ ] The workspace shows merged logs with visible source identity. -- [ ] The implementation stays within native Studio workspace boundaries. - -## Dependencies - -- Accepted `DEC-0022`. -- `PLN-0042` shared execution session and log contracts. - -## Risks - -- The first-wave UI may accidentally hardcode temporary choices that later feel permanent. -- Workspace ownership may drift into session ownership if bindings are not kept one-way. diff --git a/discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md b/discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md deleted file mode 100644 index 03835aa4..00000000 --- a/discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -id: PLN-0044 -ticket: studio-debugger-workspace-integration -title: Ordered Plan 4 - Runtime handshake integration from selective debugger knowledge -status: review -created: 2026-04-06 -completed: -tags: [studio, debugger, runtime, handshake, remote-connection] ---- - -## Objective - -Integrate the minimum runtime/debug-session handshake needed for the current flow, using selective knowledge from `../debugger` without creating a project linkage. - -## Background - -`DEC-0022` allows handshake details to be derived from `../debugger` while keeping Studio-native boundaries. `DEC-0021` reserves `debug` for the future but requires enough session behavior to support the current `run` flow and debugger destination. - -## Scope - -### Included -- Study and selectively port the useful runtime-handshake behavior from `../debugger`. -- Implement Studio-native handshake/session integration code. -- Publish handshake state into the shared execution session boundary. - -### Excluded -- Composite build or live dependency on `../debugger`. -- Full debugger feature parity. -- Profiler behavior. -- Manual rich connection-control UI. - -## Execution Steps - -### Step 1 - Identify the useful handshake slice - -**What:** Isolate the exact handshake/protocol/session behavior needed from `../debugger`. -**How:** Read the sibling repo and extract only the minimum details necessary for the current run/debug-session handshake. Do not mirror the standalone app structure. -**File(s):** Study `../debugger`; implement only Studio-native targets under `prometeu-studio`. - -### Step 2 - Implement a Studio-native handshake service - -**What:** Add handshake/session integration code in Studio-native shape. -**How:** Create a dedicated service or adapter layer that can publish `connecting`, `connected`, and failure information into the shared execution session. -**File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent service package. - -### Step 3 - Connect the handshake to the shared session - -**What:** Make handshake outcomes visible to shell and workspace consumers. -**How:** Feed successful and failed handshake events into the session state machine and merged logs without requiring the visual workspace to own the protocol. -**File(s):** shared session service, handshake adapter/service, tests. - -## Test Requirements - -### Unit Tests -- Verify handshake success updates the shared session to the expected connected/running path. -- Verify handshake failure updates the shared session to a failure state and emits visible log output. - -### Integration Tests -- Simulate the runtime handshake sequence and confirm session consumers receive the expected state transitions. - -### Manual Verification -- Run a development build and confirm the session reflects connecting/connected/failed without needing the standalone debugger app. - -## Acceptance Criteria - -- [ ] Studio contains a native handshake/service implementation shaped for the current flow. -- [ ] No technical linkage to `../debugger` is introduced. -- [ ] Shared session state reflects handshake success and failure. -- [ ] The implementation selectively reuses useful debugger knowledge without wholesale copying. - -## Dependencies - -- Accepted `DEC-0021` and `DEC-0022`. -- `PLN-0042` shared execution session and log contracts. -- `PLN-0043` first-wave debug workspace surface. - -## Risks - -- Porting too much from `../debugger` could drag standalone assumptions into Studio. -- Porting too little may leave the current flow without a stable enough handshake. diff --git a/discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md b/discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md deleted file mode 100644 index 8f47dd10..00000000 --- a/discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: PLN-0045 -ticket: studio-play-stop-cartridge-flow -title: Ordered Plan 5 - End-to-end Play/Stop execution flow through shipper and DebugWorkspace -status: review -created: 2026-04-06 -completed: -tags: [studio, play-stop, runtime, debugger, shipper, shell] ---- - -## Objective - -Wire the full first-wave `Play/Stop` flow end-to-end through shipper preparation, shared execution session state, native debugger destination, external runtime execution, and direct-stop behavior. - -## Background - -`DEC-0020`, `DEC-0021`, and `DEC-0022` together now define the intended first-wave behavior. This plan is intentionally last because it integrates the service, session, workspace, and handshake pieces established in the earlier plans. - -## Scope - -### Included -- `Play` navigation to the debugger destination at flow start. -- Invocation of shipper preparation. -- Propagation of preparation failure into the shared session and debugger destination. -- External runtime spawn `"" run build` in project root. -- Runtime output publication into shared session and debugger destination. -- Direct runtime kill on `Stop`. - -### Excluded -- Preparation cancellation. -- Drift/freshness reuse. -- `debug` command path. -- Profiler behavior. - -## Execution Steps - -### Step 1 - Wire `Play` into the shared execution destination - -**What:** Make pressing `Play` move the user into the debugger destination immediately. -**How:** Navigate to `DebugWorkspace` at the beginning of the flow, before runtime spawn, so preparation failures also appear there. -**File(s):** shell/play controls, workspace selection/navigation logic, `MainView` or equivalent shell coordinator code. - -### Step 2 - Invoke shipper preparation and reflect preparation state - -**What:** Start the shipper service and reflect `preparing` / `prepare_failed`. -**How:** Transition the shared execution session into `preparing`, consume shipper aggregated preparation output, and stop on first preparation failure. -**File(s):** play orchestration layer, shared session service adapters, shell controls. - -### Step 3 - Spawn the external runtime process - -**What:** Execute the exact current-wave runtime command. -**How:** Use `ProjectLocalStudioSetup.prometeuRuntimePath` and spawn `"" run build` with `cwd = project root`. Transition through `connecting`, then `running`, or `runtime_failed` on failure. -**File(s):** runtime orchestration service, shell controls, process-management code. - -### Step 4 - Wire `Stop` semantics - -**What:** Kill the active runtime process directly. -**How:** Keep one active process handle. Ignore repeated `Play` while active. During `preparing`, `Stop` remains a no-op because cancellation is out of scope. -**File(s):** play/stop controls, runtime orchestration service, shared session service. - -### Step 5 - Close the end-to-end loop - -**What:** Ensure all logs and state transitions reach the debugger destination consistently. -**How:** Route shipper preparation output plus runtime output into the shared session/log sink. Keep the Activity Feed summary-only. -**File(s):** orchestration layer, shared session adapters, workspace bindings. - -## Test Requirements - -### Unit Tests -- Verify `Play` transitions the session to `preparing` before runtime spawn. -- Verify repeated `Play` is ignored while runtime is active. -- Verify `Stop` kills the active runtime process and does nothing during `preparing`. -- Verify spawn failures become runtime preflight failures. - -### Integration Tests -- End-to-end success path: `Play` opens debugger destination, prepares successfully, spawns runtime, and exposes logs/state. -- Build failure path: debugger destination opens and shows preparation failure without runtime spawn. -- Pack-validation failure path: debugger destination opens and shows preparation failure without runtime spawn. -- Runtime spawn failure path: debugger destination opens and shows runtime failure after successful preparation. - -### Manual Verification -- Press `Play` in Studio and confirm the shell navigates to `Debug`. -- Confirm preparation logs appear before runtime output. -- Confirm `Stop` kills a running runtime process. -- Confirm repeated `Play` while running is ignored. - -## Acceptance Criteria - -- [ ] `Play` opens the debugger destination immediately. -- [ ] The flow executes shipper preparation before runtime spawn. -- [ ] Preparation failures remain visible in the debugger destination. -- [ ] Runtime spawn uses the exact command and working-directory contract from `DEC-0021`. -- [ ] `Stop` kills only the active runtime process and does not cancel preparation. -- [ ] The debugger destination shows merged preparation and runtime logs end-to-end. - -## Dependencies - -- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`. -- `PLN-0041` shipper preparation foundation. -- `PLN-0042` shared execution session and log contracts. -- `PLN-0043` first-wave `DebugWorkspace` surface. -- `PLN-0044` runtime handshake selective integration. - -## Risks - -- End-to-end orchestration may reintroduce ownership confusion if shell, shipper, and debugger boundaries are not kept strict. -- UI timing issues may surface when navigating to the debugger before preparation output begins. -- Process-lifecycle bugs can leave the shell believing a runtime is still active after failure.