---
id: PLN-0042
ticket: studio-play-stop-cartridge-flow
title: Ordered Plan 2 - Shared execution session and merged log contracts
status: review
created: 2026-04-06
completed:
tags: [studio, play-stop, debugger, session, logs, state]
---

## Objective

Define and implement the shared execution-session boundary that exists outside visual workspace lifecycle and carries state plus merged log contracts for preparation and runtime.

## Background

`DEC-0021` and `DEC-0022` require a shared state machine and a merged log destination independent of the visual `DebugWorkspace`. `DEC-0020` requires shipper-owned preparation log aggregation.

This plan is intentionally cross-cutting and must land before the final orchestration and workspace consumption plans.

## Scope

### Included
- Shared session/service boundary outside the visual workspace.
- Minimum shared state machine: `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, `stopped`.
- Structured merged log-entry contract with visible source identity.
- Adapters for shipper-owned preparation output and runtime output to feed the shared session.

### Excluded
- Final debugger workspace UI.
- Runtime process spawning details.
- Full handshake implementation details.
- Profiler behavior.

## Execution Steps

### Step 1 - Define shared state and session contracts

**What:** Introduce shared types and services for execution-session state.
**How:** Create a Studio-owned session/service API not tied to `Workspace` lifecycle. Add explicit transitions for the minimum required states.
**File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent shared execution package.

### Step 2 - Define merged log-entry contracts

**What:** Add a structured log-entry model for merged execution logs.
**How:** Require at least `source`, `message`, `severity`, and ordering metadata such as timestamp/sequence. Preserve the source channels `build`, `pack-validation`, `pack`, and `runtime`.
**File(s):** shared execution/debug model package, service interfaces, DTOs/events.

### Step 3 - Connect shipper output to the shared session

**What:** Feed shipper-owned preparation output into the shared session boundary.
**How:** Adapt the shipper result/log stream into session log entries and preparation state transitions without moving ownership away from shipper.
**File(s):** shipper adapters, shared session service, orchestration glue.

### Step 4 - Connect runtime output to the shared session

**What:** Reserve the runtime side of the merged stream and state transitions for later orchestration plans.
**How:** Define append/update APIs now so later runtime plans can publish `connecting`, `running`, `runtime_failed`, and `stopped` without changing the contract shape.
**File(s):** shared session/service types and tests.

## Test Requirements

### Unit Tests
- Verify legal state transitions for the minimum state machine.
- Verify merged log entries preserve source identity and ordering metadata.
- Verify shipper output can be appended without collapsing channels.

### Integration Tests
- Feed a simulated preparation success/failure sequence into the shared session and assert resulting state and log stream.
- Verify the shared session survives workspace recreation or absence.

### Manual Verification
- Inspect a development build and confirm execution state remains available even if the visual debug surface is not yet mounted.

## Acceptance Criteria

- [ ] A shared execution-session service exists outside the visual workspace lifecycle.
- [ ] The minimum state machine is explicitly implemented.
- [ ] Merged log entries preserve source identity for `build`, `pack-validation`, `pack`, and `runtime`.
- [ ] Shipper preparation output can flow into the shared session without changing shipper ownership.

## Dependencies

- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
- `PLN-0041` shipper preparation foundation.

## Risks

- State transitions may become duplicated between shell, workspace, and service if ownership is not kept strict.
- Log models that are too thin will force churn once the debugger surface exists.
- Overdesign here could slow down the simple first wave the decisions explicitly allow.