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