housekeep

This commit is contained in:
2026-04-07 05:33:18 +01:00
parent 49b2715158
commit 5b03fe6cfd
13 changed files with 58 additions and 1437 deletions
@@ -1,147 +0,0 @@
---
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.
@@ -1,174 +0,0 @@
---
id: DEC-0021
ticket: studio-play-stop-cartridge-flow
title: Decision for Play/Stop runtime execution from build through external run process
status: accepted
created: 2026-04-06
accepted: 2026-04-06
agenda: AGD-0024
plans: [PLN-0042, PLN-0044, PLN-0045]
tags: [studio, runtime, play-stop, build, process, debugger, project-setup, logs]
---
## Decision
Domain owner: `studio`.
Referenced subdomains: `runtime`.
This decision defines the runtime-execution contract that follows the preparation contract already described in `DEC-0020`.
The decision is:
1. `Play` MUST execute the configured runtime as an external process.
2. The runtime executable path MUST come from `ProjectLocalStudioSetup.prometeuRuntimePath`.
3. The external command for this wave MUST be exactly `"<runtimePath>" run build`.
4. The process MUST run with the project root as its current working directory.
5. `Play` MUST rely on the successful completion of the preparation pipeline and MUST NOT add a redundant manifest-existence preflight in this wave.
6. `Play` MUST fail explicitly when the configured runtime path is missing, invalid, nonexistent, non-executable, or cannot be spawned.
7. `Play` MUST own exactly one active runtime-process handle for the current project shell.
8. While that process is active, additional `Play` actions MUST be ignored.
9. `Stop` in this wave MUST kill the active runtime process directly.
10. The future `DebuggerWorkspace` SHALL be the canonical destination of execution and logs.
11. Until that workspace exists, runtime logs and shipper-provided preparation logs MUST flow to a temporary surface, while the Activity Feed only receives summarized lifecycle events.
12. The shipper service remains the owner of preparation orchestration and aggregated preparation output.
13. The `pack` step used by `Play` MUST preserve validation before packing, and runtime execution MUST NOT start if validation blocks the pack.
14. Additional pre-build editor preflight checks, including unsaved-file detection, are explicitly deferred to a future wave.
15. No cancellation of the preparation phase is supported in this wave.
16. The future debugger wave MAY replace `run` with `debug`, but that is not authorized by this decision.
## Rationale
`Play/Stop` only becomes semantically real if the shell owns the runtime process it claims to start and stop.
After `DEC-0020`, the runnable artifact root for this wave is `build/`, and the preparation flow already owns generation of `manifest.json`.
This means the runtime-execution wave does not need another packaging boundary and does not need redundant manifest-existence checks before spawn.
The narrowest correct contract is therefore:
- prepare through `build -> validate pack -> pack -> manifest`,
- treat shipper as the owner of preparation output and aggregated preparation logs,
- spawn the configured runtime externally with `run build`,
- keep a single process handle,
- and surface logs in the future debugger destination.
This keeps responsibility boundaries clear:
- preparation remains owned by the earlier preparation decision,
- runtime-process ownership belongs to the shell,
- and future debugger behavior remains a later wave rather than being guessed now.
## Technical Specification
### 1. Runtime Command
For this wave, the Studio shell MUST construct and execute the runtime command as:
`"<runtimePath>" run build`
Rules:
- `runtimePath` MUST be read from `ProjectLocalStudioSetup.prometeuRuntimePath`;
- the process MUST execute with `cwd` equal to the project root;
- no wrapper command is introduced in this wave;
- no `debug` subcommand is introduced in this wave.
### 2. Execution Order
`Play` preparation and execution MUST follow this order:
1. `build`
2. `pack` validation
3. `pack` only if validation allows it
4. runtime spawn with `run build`
The shell MUST stop on first failure.
If `build` fails, no pack validation, pack, or runtime spawn occurs.
If pack validation blocks, no pack or runtime spawn occurs.
If pack fails, runtime spawn does not occur.
If preparation fails, no cancellation path is offered in this wave; the flow simply terminates in failure.
### 3. Preparation Contract Reliance
This decision depends on `DEC-0020`.
Rules:
- the shell MUST rely on the success of the earlier preparation pipeline;
- the shell MUST NOT add a redundant check for `build/manifest.json` existence before spawn in this wave;
- a missing manifest after successful preparation is a violation of the earlier preparation contract, not a new runtime-execution rule.
### 4. Runtime Preflight
Before spawning the external process, the shell MUST treat the following conditions as explicit preflight failures:
- missing `prometeuRuntimePath`,
- blank `prometeuRuntimePath`,
- nonexistent runtime path,
- non-executable runtime path,
- spawn failure.
This wave does not yet define a broader runtime repair flow.
### 5. Process Ownership and Stop Semantics
The shell MUST own exactly one active runtime-process handle per active project shell.
Rules:
- `Play` while the process is active MUST be ignored;
- `Stop` MUST target only the process started by the current `Play` flow;
- `Stop` in this wave MUST kill that process directly;
- `Stop` has no effect during `preparing` because preparation cancellation is not defined in this wave;
- graceful debugger-oriented stop commands are deferred to a future debugger wave.
### 6. Logging and Debugger Destination
The canonical destination for execution-session logs SHALL be the future `DebuggerWorkspace`.
For this wave:
- the shell MUST navigate toward that execution destination when `Play` starts, before runtime spawn is attempted;
- logs from `build`, pack validation, `pack`, and runtime stdout/stderr MUST converge on that execution-log destination;
- preparation logs arrive there through shipper-owned aggregated output;
- until the `DebuggerWorkspace` exists, those logs MUST use a temporary/transitional surface;
- the Activity Feed MUST remain a summary surface and MUST NOT become the primary full-log destination.
### 7. Shared Session State
The Studio shell and debugger destination require shared execution state that exists independently of the visual lifecycle of the workspace.
For this wave, the minimum state machine SHALL distinguish at least:
- `idle`
- `preparing`
- `prepare_failed`
- `connecting`
- `running`
- `runtime_failed`
- `stopped`
This state is not owned solely by the visual workspace.
### 8. Deferred Checks
This decision explicitly defers:
- unsaved-editor-file checks before `build`,
- broader build preflight policy,
- graceful runtime stop commands,
- debugger-specific execution semantics,
- and any redundant manifest-presence preflight beyond the contract already owned by `DEC-0020`.
When introduced later, those concerns MUST be handled in a separate discussion wave or explicit revision.
## Constraints
1. This decision covers external runtime execution through `run`, not debugger execution through `debug`.
2. This decision assumes the preparation contract of `DEC-0020` without reopening it.
3. This decision does not yet define the concrete temporary UI surface that will host execution logs before the `DebuggerWorkspace` exists.
4. This decision does not yet define richer exit-code UX beyond success/failure lifecycle handling.
5. This decision does not yet define restart semantics beyond ignoring repeated `Play` while active.
## Revision Log
- 2026-04-06: Initial draft from AGD-0024.
@@ -1,203 +0,0 @@
---
id: DEC-0022
ticket: studio-debugger-workspace-integration
title: Decision for native Studio DebugWorkspace integration with selective debugger migration
status: accepted
created: 2026-04-06
accepted: 2026-04-06
agenda: AGD-0009
plans: [PLN-0042, PLN-0043, PLN-0044, PLN-0045]
tags: [studio, debugger, workspace, integration, logs, runtime, play-stop]
---
## Decision
Domain owner: `studio`.
Cross-domain reference: sibling repo `../debugger`.
Normative upstream dependencies: `DEC-0020`, `DEC-0021`.
This decision defines the first integration wave of `DebugWorkspace` inside Studio.
The decision is:
1. `Debug` in Studio MUST become a real native workspace, not an external launcher.
2. This integration MUST remain compatible with `DEC-0020` and `DEC-0021` and MUST NOT reinterpret preparation or execution contracts by inference.
3. The first wave of `DebugWorkspace` MUST focus on two capabilities only:
- runtime/debug-session handshake sufficient for the current `Play/Stop` flow,
- and merged execution-log sinking for preparation and runtime.
4. The first wave does NOT need to be perfect. A simple but functional session state and log sink is sufficient.
5. The `../debugger` repository MUST be treated as architectural reference and selective source of useful details, not as a dependency to be linked or a codebase to be copied wholesale.
6. Studio MUST NOT create a technical linkage between the two projects for this wave.
7. Copying code from `../debugger` MUST be avoided by default, but MAY be done selectively when concretely useful.
8. The correct integration boundary is in useful session/protocol/remote-debug policy details, not in `Application`/`Stage` bootstrap or standalone UI hosting.
9. `Play/Stop` MUST continue owning connect/attach/disconnect behavior under the hood in this wave.
10. `DebugWorkspace` MUST consume shipper-provided aggregated preparation logs and runtime logs through a shared session/service boundary.
11. `DebugWorkspace` MUST be the destination for merged logs from `build`, pack validation, `pack`, and runtime execution.
12. Build and pack remain owners of their own logs, but the user-facing execution surface MUST show those logs merged in the debugger destination.
13. The global Activity Feed MUST remain a summary surface rather than the primary raw-log destination.
14. The first wave MUST exclude profiler-specific behavior.
15. The standalone `../debugger` MUST NOT be evolved as part of this Studio integration and is expected to be removed once Studio becomes mature enough to replace it.
## Rationale
Recent `Play/Stop` decisions made `DebugWorkspace` no longer speculative.
`DEC-0021` already establishes that:
- `Play` navigates toward the future debugger destination,
- build, pack-validation, pack, and runtime logs converge there,
- and `Play/Stop` owns the current run-process contract.
That means the immediate job of agenda 9 is not to design the final debugger product.
Its immediate job is to provide the native Studio surface that can host:
- session state,
- handshake with the runtime,
- and a merged sink for execution-related logs.
The existing `../debugger` still matters, but mostly as a source of tested ideas and useful protocol/session details.
Treating it as a live dependency would be the wrong topological move because:
- the Studio is intended to become the durable host,
- the sibling debugger will be removed later,
- and hard-linking the repositories now would increase migration cost for little value.
The narrowest correct answer is therefore:
- native `DebugWorkspace` in Studio,
- selective migration only,
- no direct project linkage,
- a shared session/service boundary outside the visual workspace,
- no profiler in the first cut,
- and enough runtime handshake + log sinking to support the already-decided `Play/Stop` flow.
## Technical Specification
### 1. Upstream Contract Boundaries
This decision is downstream of `DEC-0020` and `DEC-0021`.
Rules:
- `DEC-0020` remains authoritative for preparation through `build -> validate pack -> pack -> manifest`;
- `DEC-0021` remains authoritative for runtime execution through external `"<runtimePath>" run build` and current `Play/Stop` process ownership;
- this decision MUST NOT redefine those flows;
- any attempt to change preparation or execution semantics requires explicit revision of the upstream decisions rather than reinterpretation here.
### 2. First-Wave Scope
The first-wave `DebugWorkspace` MUST provide:
- a native Studio workspace surface,
- basic debug/run session state,
- handshake behavior with the runtime sufficient for the current flow,
- and a merged log sink for execution-related activity.
The first wave MAY be visually simple.
It does not need polished debugger UX yet.
### 3. Session and Handshake
The workspace MUST expose enough session state to show at least:
- connecting,
- connected,
- failed,
- and equivalent stopped/disconnected state as needed by the current flow.
Handshake details MAY be derived from `../debugger` where useful, but MUST be integrated into Studio-native session/workspace boundaries.
For this wave:
- `Play/Stop` remains the owner of under-the-hood connect/attach/disconnect behavior;
- `DebugWorkspace` is the native surface that reflects and hosts that session;
- the underlying session state MUST exist outside the visual workspace lifecycle so the Studio shell can react to it globally.
### 4. Logging
The `DebugWorkspace` MUST be the merged sink destination for:
- `build` logs,
- pack-validation logs,
- `pack` logs,
- runtime stdout/stderr.
Rules:
- build and pack keep ownership of their own log production;
- shipper owns the aggregation of preparation logs for user-facing consumption;
- the debugger destination consumes merged preparation output plus runtime logs;
- the initial merged sink MAY be a simple console/list with visible source/origin labels;
- source/origin labels MUST preserve at least `build`, `pack-validation`, `pack`, and `runtime`;
- the merged sink does not need sophisticated structure in the first wave;
- the Activity Feed MUST only carry summarized lifecycle signals.
### 5. Shared Session State
The first-wave debugger integration MUST consume a shared session/service boundary that is not owned solely by the visual workspace.
At minimum, that shared state MUST distinguish:
- `idle`
- `preparing`
- `prepare_failed`
- `connecting`
- `running`
- `runtime_failed`
- `stopped`
The `DebugWorkspace` consumes and reflects this state.
### 6. Integration Topology
The integration topology for this wave MUST be selective migration into Studio.
Rules:
- no composite build or equivalent live technical linkage with `../debugger`;
- no requirement to keep the standalone debugger as a parallel supported surface;
- no wholesale copy by inertia;
- selective code migration is allowed when concretely useful.
The intended direction is:
- Studio becomes the durable host,
- `../debugger` is not extended further for this effort,
- and the sibling project may be removed once Studio matures enough.
### 7. Native Studio Shape
`DebugWorkspace` MUST obey native Studio workspace rules for:
- lifecycle,
- event-bus integration,
- theming,
- i18n,
- navigation under the Studio shell.
This decision does not authorize embedding the standalone debugger bootstrap as the main integration unit.
### 8. Explicit Exclusions
This decision does not yet define:
- profiler integration,
- polished final debugger UX,
- a rich manual connect/disconnect control surface,
- a final structured logging model,
- cancellation of preparation,
- or any change from `run` to `debug` in the runtime command path.
Those concerns remain future waves.
## Constraints
1. This decision is subordinate to `DEC-0020` and `DEC-0021`.
2. This decision defines the first wave of `DebugWorkspace`, not the complete debugger product.
3. This decision assumes selective use of `../debugger` knowledge/details without creating a permanent dependency.
4. This decision does not authorize profiler behavior.
5. This decision does not authorize changing current `Play/Stop` ownership semantics.
## Revision Log
- 2026-04-06: Initial draft from AGD-0009.