237 lines
10 KiB
Markdown
237 lines
10 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.
|
|
|
|
Rules:
|
|
|
|
- validation runs on the same pack set used by summary:
|
|
`registered + included in build`;
|
|
- validation is read-only, non-mutating, and snapshot-backed;
|
|
- validation may reuse deep inspection or reconcile-grade logic internally;
|
|
- a future deep-sync step may run before validation in the Studio flow, but validation itself still evaluates the packer snapshot;
|
|
- only diagnostics marked `blocking` fail validation in the first wave;
|
|
- if the returned per-asset list contains no blocking diagnostics, validation is green;
|
|
- if the returned per-asset list contains any blocking diagnostics, validation is red and packing must not begin.
|
|
|
|
The first-wave validation payload should prioritize the per-asset diagnostic list over aggregate data.
|
|
|
|
Each validation item should expose:
|
|
|
|
- asset id;
|
|
- asset name;
|
|
- asset path;
|
|
- `lastModified`;
|
|
- diagnostics.
|
|
|
|
The diagnostics in this contract are blocking diagnostics only in the first wave.
|
|
|
|
Aggregate data is secondary here.
|
|
It may still exist, but it should not be treated as the primary UI payload because the Studio can derive aggregate views from the returned per-asset list if needed.
|
|
|
|
Ordering is not a packer concern for the first-wave validation payload.
|
|
The Studio may sort the returned items as it sees fit.
|
|
|
|
### 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.
|
|
|
|
### Summary Recommendation
|
|
|
|
The first-wave summary contract is now closed as a fast snapshot-backed preflight view.
|
|
|
|
Rules:
|
|
|
|
- summary is read-only and non-mutating;
|
|
- summary must return quickly from packer-owned snapshot state rather than from a deep recomputation pass;
|
|
- packer is the only source of truth for the summary;
|
|
- Studio must not reconstruct the summary from local navigator state;
|
|
- unregistered assets and excluded assets do not appear as explicit summary items;
|
|
- the summary does not anticipate emitted artifacts, companion artifacts, or `assets.pa` details in the first wave.
|
|
|
|
The first-wave summary shape should contain:
|
|
|
|
1. one aggregate count for the current pack set;
|
|
2. one per-asset list for the current pack set.
|
|
|
|
The aggregate is intentionally minimal in the first wave:
|
|
|
|
- total included asset count is enough for now.
|
|
|
|
Each per-asset summary entry should include at least:
|
|
|
|
- asset name;
|
|
- asset family;
|
|
- min artifact count for that asset;
|
|
- max artifact count for that asset;
|
|
- `lastModified` as a `long`.
|
|
|
|
`lastModified` is explicitly useful even if the packer cannot yet provide the final real value for every asset in the first implementation wave.
|
|
The contract may expose `0` temporarily, but the field should already exist so the Studio can depend on the shape and later sort against real values.
|
|
|
|
This per-asset list is the correct place for the developer-facing graphical occupancy preview per asset in the Studio shell.
|
|
The aggregate should remain intentionally small.
|
|
|
|
## Open Questions
|
|
|
|
1. Should the final pack result expose artifact paths, artifact labels, or both?
|
|
2. Should the pack execution result carry timing directly, or should timing remain event-derived metadata?
|
|
|
|
## Resolved In This Agenda Wave
|
|
|
|
The following points are now closed for `summary`:
|
|
|
|
1. summary is read-only, non-mutating, and snapshot-backed;
|
|
2. packer is the sole source of truth for summary data;
|
|
3. unregistered and excluded assets do not appear as explicit summary entries;
|
|
4. first-wave summary includes one aggregate count only:
|
|
total included asset count;
|
|
5. first-wave summary also includes a per-asset list for the current pack set;
|
|
6. each per-asset summary entry must expose:
|
|
asset name, asset family, min artifact count, max artifact count, and `lastModified`;
|
|
7. `lastModified` may temporarily be `0` until full support exists, but the field should already exist in the public contract;
|
|
8. summary does not anticipate companion artifacts or emitted artifact details in the first wave.
|
|
|
|
The following points are now closed for `validation`:
|
|
|
|
1. validation runs on the same `registered + included in build` set used by summary;
|
|
2. validation is read-only, non-mutating, and snapshot-backed;
|
|
3. only diagnostics marked `blocking` fail validation in the first wave;
|
|
4. the primary validation payload is the per-asset diagnostics list, not the aggregate;
|
|
5. each per-asset validation entry must expose:
|
|
asset id, asset name, asset path, `lastModified`, and diagnostics;
|
|
6. the diagnostics returned by validation are blocking diagnostics only in the first wave;
|
|
7. if the returned validation list contains no blocking diagnostics, validation is green;
|
|
8. if the returned validation list contains any blocking diagnostics, validation is red and packing must not begin;
|
|
9. payload ordering is not a packer responsibility in the first wave;
|
|
10. a future deep-sync step may be added before validation in the Studio flow, but validation itself still evaluates the packer snapshot.
|
|
|
|
## 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.
|