148 lines
6.3 KiB
Markdown
148 lines
6.3 KiB
Markdown
---
|
|
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.
|