204 lines
8.0 KiB
Markdown
204 lines
8.0 KiB
Markdown
---
|
|
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 `"<runtimePath>" 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.
|