prometeu-studio/discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md

id	ticket	title	status	created	completed	tags
PLN-0041	studio-play-stop-cartridge-flow	Ordered Plan 1 - Shipper preparation foundation for build, pack, and manifest	review	2026-04-06		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.