From 6649b11ec49ae01c942a2326925cddadd8eeae8f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 6 Apr 2026 06:28:22 +0100 Subject: [PATCH] dsn: debugger, play/stop, runtime --- discussion/index.ndjson | 6 +- ...9-studio-debugger-workspace-integration.md | 97 +++++++-- ...D-0023-studio-play-stop-shipper-phase-1.md | 132 ++++++++++++ ...-studio-play-stop-runtime-run-cartridge.md | 128 +++++++++++ ...studio-play-stop-build-pack-preparation.md | 147 +++++++++++++ ...studio-play-stop-runtime-run-from-build.md | 174 +++++++++++++++ ...udio-debug-workspace-native-integration.md | 203 ++++++++++++++++++ ...PLN-0041-shipper-preparation-foundation.md | 96 +++++++++ ...red-execution-session-and-log-contracts.md | 91 ++++++++ ...0043-debug-workspace-first-wave-surface.md | 90 ++++++++ ...runtime-handshake-selective-integration.md | 80 +++++++ ...045-play-stop-end-to-end-execution-flow.md | 108 ++++++++++ 12 files changed, 1330 insertions(+), 22 deletions(-) create mode 100644 discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md create mode 100644 discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md create mode 100644 discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md create mode 100644 discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md create mode 100644 discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md create mode 100644 discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md create mode 100644 discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md create mode 100644 discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md create mode 100644 discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md create mode 100644 discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 750faa31..e8c14c56 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":23,"AGD":25,"DEC":20,"PLN":41,"LSN":37,"CLSN":1}} +{"type":"meta","next_id":{"DSC":23,"AGD":25,"DEC":23,"PLN":46,"LSN":37,"CLSN":1}} {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} @@ -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-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]} +{"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-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":"open","created_at":"2026-04-06","updated_at":"2026-04-06"},{"id":"AGD-0024","file":"AGD-0024-studio-play-stop-runtime-run-cartridge.md","status":"open","created_at":"2026-04-06","updated_at":"2026-04-06"}],"decisions":[],"plans":[],"lessons":[]} +{"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":[]} diff --git a/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md b/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md index 6a5a3469..5045a146 100644 --- a/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md +++ b/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md @@ -2,10 +2,10 @@ id: AGD-0009 ticket: studio-debugger-workspace-integration title: Integrar ../debugger ao Studio como workspace dedicado -status: open +status: in_progress created: 2026-03-30 -resolved: -decision: +resolved: 2026-04-06 +decision: DEC-0022 tags: - studio - debugger @@ -37,6 +37,11 @@ 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; @@ -51,16 +56,43 @@ O boundary de produto tambem ja aponta a direcao correta: - logs e detalhe de execucao pertencem ao workspace que os possui; - o debugger e uma superficie de execucao, nao um detalhe lateral do painel global de utilidades. +As discussoes mais recentes de `Play/Stop` tambem reduziram o primeiro corte que interessa agora: + +- o `DebugWorkspace` e o destino futuro dos logs de `build`, validacao de `pack`, `pack` e runtime; +- `Play/Stop` continua dono do fluxo operacional de `run` nesta wave; +- o valor principal a reaproveitar do `../debugger` agora esta em filosofia, politicas de debug/remote connection, sessao, protocolo e modelos de eventos, nao em bootstrap de app standalone nem em copia literal de codigo; +- o objetivo imediato nao e portar "o debugger inteiro", mas sim dar ao Studio uma superficie de execucao e observabilidade nativa. +- nao precisamos comecar perfeitos: a primeira wave pode ser deliberadamente simples, desde que entregue handshake com o runtime e sink de logs suficiente para destravar `Play/Stop`. + +Constraint for this agenda: + +- esta agenda trabalha em conjunto com `AGD-0023`/`DEC-0020` e `AGD-0024`/`DEC-0021`; +- ela NAO pode reinterpretar pipeline de preparacao, politica de execucao, ownership de `Play/Stop` ou trocar `run` por `debug` por inferencia; +- qualquer mudanca nesses contratos exige revisao explicita das decisions upstream, nao convergencia lateral dentro desta agenda. + ## Open Questions -- [ ] O objetivo da primeira integracao e hospedar a experiencia atual do `../debugger` quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio? -- [ ] Quais partes do `../debugger` sao `core` reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira? -- [ ] Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo? -- [ ] 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? -- [ ] 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? -- [ ] O primeiro corte deve incluir `profiler` junto com `debugger`, ou o baseline inicial fecha apenas `debugger` e deixa profiling como extensao posterior? +- [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? -- [ ] O app standalone `../debugger` continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario? +- [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 @@ -76,11 +108,11 @@ O boundary de produto tambem ja aponta a direcao correta: - **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 apoiado em core extraido do debugger -- **Approach:** Tratar o `../debugger` como fonte de servicos, protocolo, estado e controle de execucao reaproveitaveis, mas implementar o `DebugWorkspace` como composicao nativa do Studio sobre o contrato `Workspace` + bus tipado + lifecycle-managed controls. +### 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 `core` reutilizavel e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico. -- **Maintainability:** Forte. Preserva a direcao arquitetural correta e permite que Studio e app standalone compartilhem nucleo sem colapsarem num acoplamento acidental. +- **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. @@ -96,6 +128,12 @@ O ponto principal nao e "como mostrar alguma tela de debug no Studio". O ponto p - 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. @@ -109,6 +147,21 @@ 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. @@ -119,9 +172,15 @@ 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 boundary correto de reaproveitamento esta em servicos/protocolo/estado do debugger, nao no bootstrap `Application`/`Stage` como unidade de integracao; -3. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n; -4. o destino do app standalone precisa ser explicitado: consumidor paralelo do mesmo core durante migracao, ou superficie secundaria apos a integracao; -5. o primeiro corte deve declarar se `profiler` entra junto com `debugger` ou fica explicitamente fatiado para depois. +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`. +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 new file mode 100644 index 00000000..05ccfa8b --- /dev/null +++ b/discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md @@ -0,0 +1,132 @@ +--- +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 new file mode 100644 index 00000000..aa1a0358 --- /dev/null +++ b/discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md @@ -0,0 +1,128 @@ +--- +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 new file mode 100644 index 00000000..58639240 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md @@ -0,0 +1,147 @@ +--- +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 new file mode 100644 index 00000000..267bbbe9 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md @@ -0,0 +1,174 @@ +--- +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 new file mode 100644 index 00000000..8d6cdddd --- /dev/null +++ b/discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md @@ -0,0 +1,203 @@ +--- +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 new file mode 100644 index 00000000..e48f5160 --- /dev/null +++ b/discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md @@ -0,0 +1,96 @@ +--- +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 new file mode 100644 index 00000000..6216c062 --- /dev/null +++ b/discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md @@ -0,0 +1,91 @@ +--- +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 new file mode 100644 index 00000000..af5fef3e --- /dev/null +++ b/discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md @@ -0,0 +1,90 @@ +--- +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 new file mode 100644 index 00000000..03835aa4 --- /dev/null +++ b/discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md @@ -0,0 +1,80 @@ +--- +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 new file mode 100644 index 00000000..8f47dd10 --- /dev/null +++ b/discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md @@ -0,0 +1,108 @@ +--- +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.