92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
---
|
|
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.
|