153 lines
6.2 KiB
Markdown
153 lines
6.2 KiB
Markdown
# Pack Wizard Studio Decision Propagation Agenda
|
|
|
|
## Status
|
|
|
|
Open
|
|
|
|
## Purpose
|
|
|
|
Converge the packer-side discussion required to propagate the Studio `Pack Wizard` decision into packer-owned public contracts.
|
|
|
|
The immediate goal is not to implement packing behavior yet.
|
|
The goal is to close how the packer should expose summary, validation, execution, progress, and result contracts so Studio can remain a shell over packer-owned semantics.
|
|
|
|
This agenda is driven by the Studio-side decision:
|
|
|
|
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
|
|
|
## Context
|
|
|
|
The new Studio decision already closes several boundary rules:
|
|
|
|
- Studio is a modal shell only;
|
|
- packer owns `summary`, `validation`, `pack execution`, progress, and result semantics;
|
|
- the wizard has four explicit phases:
|
|
`Summary`, `Validation`, `Packing`, `Result`;
|
|
- the pack set is the current `registered + included in build` set;
|
|
- blocking diagnostics in that set fail validation;
|
|
- the first wave is non-cancelable;
|
|
- `assets.pa` remains the canonical emitted artifact.
|
|
|
|
What remains open on the packer side is the exact API and DTO shape that should support this flow cleanly.
|
|
|
|
Important current constraints:
|
|
|
|
1. `PackerWorkspaceService` already exposes multiple operation-specific request/response pairs rather than one giant command surface;
|
|
2. the public API already has stable patterns for:
|
|
- `...Request`
|
|
- `...Result`
|
|
- `PackerOperationStatus`
|
|
- event-driven progress through `PackerEvent` and `PackerProgress`;
|
|
3. the build artifact spec already defines `assets.pa` authority and deterministic `asset_table` rules;
|
|
4. the Studio decision explicitly requires three distinct calls:
|
|
`summary`, `validation`, and `pack execution`.
|
|
|
|
This means the packer should extend an existing contract style where possible instead of inventing a one-off build wizard protocol.
|
|
|
|
## Options
|
|
|
|
### Option A - Three new public operations with dedicated request/result DTOs
|
|
|
|
Add three explicit public operations to `PackerWorkspaceService`:
|
|
|
|
1. summary
|
|
2. validation
|
|
3. pack execution
|
|
|
|
Each operation gets dedicated request/result messages, with nested DTOs where needed.
|
|
|
|
Progress continues through the existing event path.
|
|
|
|
### Option B - One `pack` command plus phase-rich result objects
|
|
|
|
Expose one public `pack` call and let Studio infer phases from intermediate result payloads and packer events.
|
|
|
|
Summary and validation would become either optional preflight flags or internal behavior hidden behind one command.
|
|
|
|
### Option C - Composite build session contract
|
|
|
|
Create a higher-level `PackSession` or similar build-session API that owns summary, validation, execution, and result under one larger protocol object.
|
|
|
|
Studio would talk to that session abstraction rather than to simple operation methods.
|
|
|
|
## Tradeoffs
|
|
|
|
- Option A matches the existing public API style best and aligns with the Studio decision directly.
|
|
- Option A also makes each phase testable and reusable without forcing execution.
|
|
- Option A increases DTO count, but the surface stays explicit and predictable.
|
|
- Option B reduces top-level API additions, but it hides too much semantic structure from Studio and pushes phase reconstruction into the host.
|
|
- Option B also weakens the explicit preflight/value of `summary` and `validation`.
|
|
- Option C could become elegant later if the build system grows more modes, but it is too heavy for the current wave and risks introducing a second API style beside the existing `PackerWorkspaceService` request/result pattern.
|
|
|
|
## Recommendation
|
|
|
|
Adopt `Option A`.
|
|
|
|
The packer should expose three explicit public operations and keep them aligned with the existing API style.
|
|
|
|
Recommended first-wave contract direction:
|
|
|
|
1. add `PackWorkspaceSummaryRequest` / `PackWorkspaceSummaryResult`;
|
|
2. add `ValidatePackWorkspaceRequest` / `ValidatePackWorkspaceResult`;
|
|
3. add `PackWorkspaceRequest` / `PackWorkspaceResult`;
|
|
4. add focused DTOs for:
|
|
- pack summary
|
|
- per-asset validation status
|
|
- validation aggregate
|
|
- emitted artifact summary
|
|
- final pack result summary
|
|
5. reuse existing public primitives where they already fit:
|
|
- `PackerProjectContext`
|
|
- `PackerOperationStatus`
|
|
- `PackerDiagnosticDTO`
|
|
- `PackerProgress`
|
|
- existing event publication path for operation progress.
|
|
|
|
### Boundary Recommendation
|
|
|
|
The packer contract should state clearly:
|
|
|
|
- summary is read-oriented and non-mutating;
|
|
- validation is dry-run-like and non-emitting;
|
|
- pack execution is the only operation that actually emits build artifacts.
|
|
|
|
### Validation Recommendation
|
|
|
|
The validation contract should be build-set-scoped and asset-oriented.
|
|
|
|
It should return at least:
|
|
|
|
- aggregate counts;
|
|
- whether packing is allowed;
|
|
- per-asset validation entries for assets in scope;
|
|
- blocking diagnostics for default display;
|
|
- enough detail for Studio drill-down without local recomputation.
|
|
|
|
### Execution Recommendation
|
|
|
|
The execution contract should keep final result summary separate from progress.
|
|
|
|
Progress should continue to flow through the existing packer event system rather than being duplicated into polling-oriented response DTOs for the first wave.
|
|
|
|
The final result should describe:
|
|
|
|
- final status;
|
|
- emitted canonical artifact `assets.pa`;
|
|
- emitted companion artifacts where available;
|
|
- total assets packed;
|
|
- duration or equivalent timing summary when available.
|
|
|
|
## Open Questions
|
|
|
|
1. Should validation result DTOs include all diagnostics in scope or only the subset relevant to the pack gate by default?
|
|
2. Should the final pack result expose artifact paths, artifact labels, or both?
|
|
3. Does the first-wave summary contract need companion artifact preview data, or is `assets.pa` plus counts enough before execution?
|
|
4. Should the pack execution result carry timing directly, or should timing remain event-derived metadata?
|
|
|
|
## Expected Follow-up
|
|
|
|
1. Convert this agenda into a packer `decision` that closes the public API shape.
|
|
2. Execute a packer PR that adds the public contracts in `prometeu-packer-api`.
|
|
3. Follow with a packer implementation PR in `prometeu-packer-v1` for summary, validation, progress, and pack execution behavior.
|
|
4. Follow with a Studio PR to bind the wizard shell to the new packer contracts.
|