prometeu-studio/discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md

id	ticket	title	status	created	completed	tags
PLN-0042	studio-play-stop-cartridge-flow	Ordered Plan 2 - Shared execution session and merged log contracts	review	2026-04-06		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.