packer (WIP)
This commit is contained in:
@@ -0,0 +1,152 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user