Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md

8.0 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0022 studio-debugger-workspace-integration Decision for native Studio DebugWorkspace integration with selective debugger migration accepted 2026-04-06 2026-04-06 AGD-0009
PLN-0042
PLN-0043
PLN-0044
PLN-0045
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.