prometeu-studio/discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0020	studio-play-stop-cartridge-flow	Decision for Play/Stop build and pack preparation through build-owned artifacts	accepted	2026-04-06	2026-04-06	AGD-0023	PLN-0041 PLN-0042 PLN-0045	studio play-stop build pack compiler packer manifest shell

Decision

Domain owner: studio. Referenced subdomains: compiler, packer, runtime.

The Studio Play flow for this wave SHALL be implemented as an orchestration over existing domain operations, not as a separate shipping pipeline.

The decision is:

1. Play MUST call build first.
2. pack MUST run only after build completes successfully.
3. Play MUST treat build/ as the runnable artifact root for this wave.
4. Play MUST NOT materialize or depend on a separate cartridge/ directory in this wave.
5. manifest.json MUST be generated deterministically into build/ from the current build result and project-owned metadata.
6. Play MUST only need to evaluate whether each required operation succeeded or failed.
7. Detailed operation logs MUST remain available alongside the operation results consumed by Play.
8. The Studio shipper service MUST own preparation orchestration and preparation-log aggregation for this wave.
9. Preparation logs MUST preserve at least the distinct channels build, pack-validation, and pack.
10. Drift/freshness reuse logic is explicitly out of scope for this wave.
11. A future drift/freshness wave MUST use domain-specific .studio/ files rather than the main session-restoration snapshot.

Rationale

This decision intentionally keeps the first executable Play wave narrow.

The repository already shows:

• compiler ownership of build/program.pbx,
• packer ownership of build/assets.pa and companion build artifacts,
• and no accepted requirement that a separate cartridge/ assembly step must exist before runtime execution.

Creating a new shipper/materialization layer now would add an extra boundary before the base Play integration exists. Likewise, pushing drift/freshness inference into Play would make the shell the owner of compiler and packer validity rules, which is the wrong boundary.

This decision therefore chooses the smallest correct operational split:

• Play orchestrates,
• shipper owns preparation orchestration and preparation-log aggregation,
• build produces compiler artifacts,
• pack produces packer artifacts,
• manifest is generated after successful preparation,
• and runtime execution in the next wave may consume build/ directly.

Technical Specification

1. Orchestration Order

The Play preparation path MUST execute in this order:

1. build
2. pack (only if build succeeded)
3. manifest generation in build/
4. handoff to the runtime-execution flow covered by a separate agenda/decision wave

Play MUST stop immediately on the first failed required step. No cancellation of the preparation phase is defined in this wave.

2. Artifact Root

For this wave, build/ is the canonical runnable artifact root.

At minimum, the prepared runtime-facing output in build/ SHALL include:

• program.pbx
• assets.pa
• manifest.json

Packer companion artifacts may remain in build/ as domain-owned outputs. They do not redefine the minimum contract required by Play.

3. Result Contract

The result contract consumed by Play for this wave MUST be binary at the control-flow level:

• success
• failed

Play MUST NOT need to interpret finer-grained reuse or freshness states in this wave. Operational logs from build, pack, and manifest generation MUST remain available so the shell can surface useful diagnostics without owning domain-specific decision logic. For this wave, those preparation logs are owned and aggregated by the Studio shipper service.

4. Manifest Generation

manifest.json MUST NOT be copied opportunistically from an older location.

Instead, it MUST be generated on every successful preparation run:

• in build/,
• from the current build result,
• and from project-owned metadata required by the runtime-facing manifest contract.

5. Drift and Freshness Deferral

This decision does not authorize a freshness-based skip path yet.

Rules:

• Play MUST NOT infer artifact validity from file presence alone.
• This wave MAY always execute build and pack when Play is pressed.
• If a later wave introduces drift/freshness control, that logic MUST be discussed separately before implementation.
• That later wave MUST keep operational metadata in dedicated domain files under .studio/, with the agreed initial direction being asset-workspace.json and editor-workspace.json.
• That later wave MUST NOT mix such metadata into .studio/state.json by convenience.

6. Boundary With Existing Workspaces

The current ShipperWorkspace scratch implementation does not become the normative backend for Play by inertia.

This decision does not require:

• a new shipping module,
• a separate cartridge-materialization directory,
• or Play-owned drift heuristics.

Existing workspaces may remain useful as manual or diagnostic surfaces, but they MUST NOT redefine the Play preparation contract established here.

7. Preparation Logging Boundary

For this wave, preparation logging MUST follow these rules:

• build and pack remain owners of their own log production;
• the Studio shipper service aggregates preparation output for user-facing consumption;
• the aggregated preparation stream MUST preserve distinct source channels for build, pack-validation, and pack;
• downstream debugger/execution surfaces consume that aggregated preparation output rather than redefining preparation ownership.

Constraints

1. This decision covers preparation only, not runtime process ownership or Stop behavior.
2. This decision does not yet define the exact manifest field mapping beyond deterministic generation from current build inputs and project metadata.
3. This decision does not yet define a drift fingerprint model.
4. Any later attempt to skip build or pack based on freshness requires a new discussion wave or explicit revision of this decision.
5. Any later reintroduction of cartridge/ as a mandatory runtime root requires a new decision or explicit revision of this one.

Revision Log

• 2026-04-06: Initial draft from AGD-0023.