Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md

5.1 KiB
Raw Blame History

id ticket title status created completed tags
PLN-0045 studio-play-stop-cartridge-flow Ordered Plan 5 - End-to-end Play/Stop execution flow through shipper and DebugWorkspace review 2026-04-06
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 "<runtimePath>" 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 "<runtimePath>" 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.