Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md

7.3 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0021 studio-play-stop-cartridge-flow Decision for Play/Stop runtime execution from build through external run process accepted 2026-04-06 2026-04-06 AGD-0024
PLN-0042
PLN-0044
PLN-0045
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 "<runtimePath>" 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:

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