97 lines
4.7 KiB
Markdown
97 lines
4.7 KiB
Markdown
---
|
|
id: PLN-0041
|
|
ticket: studio-play-stop-cartridge-flow
|
|
title: Ordered Plan 1 - Shipper preparation foundation for build, pack, and manifest
|
|
status: review
|
|
created: 2026-04-06
|
|
completed:
|
|
tags: [studio, play-stop, shipper, build, pack, manifest]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Implement the Studio shipper service as the owner of preparation orchestration for `build -> pack-validation -> pack -> manifest`, with deterministic output in `build/`.
|
|
|
|
## Background
|
|
|
|
`DEC-0020` establishes that preparation is Studio-owned, that `build/` is the runnable artifact root, and that shipper owns preparation orchestration plus aggregation of preparation logs.
|
|
|
|
This is the first and foundational plan in the family. Later plans depend on its service boundary and result contracts.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Introduce or reshape a Studio-owned shipper service boundary.
|
|
- Execute `build`, pack validation, `pack`, and manifest generation in the required order.
|
|
- Produce deterministic preparation results and failure boundaries.
|
|
- Preserve preparation log channels `build`, `pack-validation`, and `pack`.
|
|
|
|
### Excluded
|
|
- External runtime spawning.
|
|
- Debugger workspace UI.
|
|
- Runtime handshake.
|
|
- Drift/freshness reuse logic.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Define the shipper service contract
|
|
|
|
**What:** Add a Studio-owned service/API for preparation that exposes ordered preparation, result status, and preparation-log output.
|
|
**How:** Introduce dedicated types for preparation request/result and channel-aware preparation log entries. Keep the service independent from UI controls and workspaces.
|
|
**File(s):** `prometeu-studio/src/main/java/p/studio/.../shipper/*` (new package), existing `ShipperWorkspace` call sites as adapters only.
|
|
|
|
### Step 2 - Implement ordered preparation
|
|
|
|
**What:** Execute compiler build, pack validation, pack, and manifest generation through the shipper service.
|
|
**How:** Reuse existing compiler and packer entrypoints. Enforce stop-on-first-failure. Do not introduce cancellation. Ensure pack validation blocks pack when needed.
|
|
**File(s):** `prometeu-studio` service layer, packer integration call sites, manifest generation implementation.
|
|
|
|
### Step 3 - Materialize the deterministic build contract
|
|
|
|
**What:** Ensure successful preparation leaves `build/program.pbx`, `build/assets.pa`, and `build/manifest.json` in the expected state.
|
|
**How:** Keep compiler and packer domain ownership of their artifacts, but make manifest generation part of shipper success. Preserve the absence of a separate `cartridge/` root.
|
|
**File(s):** shipper implementation, manifest-generation code, any preparation DTOs/results.
|
|
|
|
### Step 4 - Publish channel-preserving preparation output
|
|
|
|
**What:** Aggregate preparation output for downstream consumption while preserving per-channel identity.
|
|
**How:** Build a merged-but-structured stream that labels entries as `build`, `pack-validation`, or `pack`. Expose it as shipper-owned output rather than UI-owned state.
|
|
**File(s):** shipper service/result/log types, adapters from compiler and packer logs.
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Verify shipper enforces the exact order `build -> pack-validation -> pack -> manifest`.
|
|
- Verify pack validation failure stops the flow before pack.
|
|
- Verify manifest generation only happens after successful build and pack.
|
|
- Verify aggregated preparation logs preserve the three required source channels.
|
|
|
|
### Integration Tests
|
|
- Exercise a successful preparation flow against a real project fixture and assert expected files exist in `build/`.
|
|
- Exercise build failure and assert pack and manifest are skipped.
|
|
- Exercise pack-validation failure and assert pack and manifest are skipped.
|
|
|
|
### Manual Verification
|
|
- Trigger shipper preparation on a real Studio project and confirm `build/` contains the expected artifacts.
|
|
- Inspect emitted preparation logs and confirm channel labels remain visible.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] A Studio-owned shipper service exists and is the sole owner of preparation orchestration.
|
|
- [ ] Preparation executes in the exact decision-ordered sequence.
|
|
- [ ] Preparation stops on first failure and does not support cancellation in this wave.
|
|
- [ ] Successful preparation leaves the required runnable files in `build/`.
|
|
- [ ] Preparation output preserves `build`, `pack-validation`, and `pack` channel identity.
|
|
|
|
## Dependencies
|
|
|
|
- Accepted `DEC-0020`.
|
|
- Existing compiler `build` entrypoint.
|
|
- Existing packer validation and pack entrypoints.
|
|
|
|
## Risks
|
|
|
|
- Hidden coupling to the current `ShipperWorkspace` scratch path may leak UI assumptions into the service boundary.
|
|
- Manifest generation may become entangled with runtime policy if not kept narrow.
|
|
- Log aggregation may collapse source identity if implemented as raw text concatenation.
|