--- id: DEC-0020 ticket: studio-play-stop-cartridge-flow title: Decision for Play/Stop build and pack preparation through build-owned artifacts status: accepted created: 2026-04-06 accepted: 2026-04-06 agenda: AGD-0023 plans: [PLN-0041, PLN-0042, PLN-0045] tags: [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.