119 lines
4.0 KiB
Markdown
119 lines
4.0 KiB
Markdown
# Pack Wizard: Summary, Validation, and Pack Execution
|
|
|
|
## Original Problem
|
|
|
|
The Studio-side wizard was already accepted as a shell over packer-owned operations, but the packer side still needed one coherent story for:
|
|
|
|
1. what `summary` means;
|
|
2. what `validation` means;
|
|
3. how `packWorkspace(...)` executes without trusting stale UI state or live filesystem rereads.
|
|
|
|
The historical agenda, decisions, and PRs solved this in slices.
|
|
This document keeps the final model in one place.
|
|
|
|
## Consolidated Decision
|
|
|
|
The first-wave `Pack Wizard` contract is phase-based and fully packer-owned:
|
|
|
|
1. `summary` is a fast snapshot-backed preflight view;
|
|
2. `validation` is a snapshot-backed gate over the same active pack set;
|
|
3. `packWorkspace(...)` is the only artifact-emitting wizard operation;
|
|
4. execution reruns the gate on a fresh frozen snapshot;
|
|
5. outputs are staged before promotion into final `build/` locations.
|
|
|
|
The active pack set is always:
|
|
|
|
`registered + included in build`
|
|
|
|
## Final Model
|
|
|
|
### 1. Summary
|
|
|
|
`summary` is not a build preview.
|
|
It is a quick packer-owned view of the current active pack set.
|
|
|
|
First-wave payload:
|
|
|
|
- total included asset count;
|
|
- one per-asset list with:
|
|
- `assetId`
|
|
- `assetName`
|
|
- `assetFamily`
|
|
- `minArtifactCount`
|
|
- `maxArtifactCount`
|
|
- `lastModified`
|
|
|
|
### 2. Validation
|
|
|
|
`validation` evaluates the same pack set as `summary`, but its job is to answer a different question:
|
|
|
|
Can packing begin?
|
|
|
|
First-wave rule:
|
|
|
|
- only `blocking` diagnostics fail validation;
|
|
- warnings are visible elsewhere, but they are not part of the first validation gate contract.
|
|
|
|
Primary payload:
|
|
|
|
- one per-asset list containing only assets with blocking diagnostics.
|
|
|
|
### 3. Pack Execution
|
|
|
|
`packWorkspace(...)` is a write-lane operation.
|
|
It does not trust that earlier summary or validation responses are still current.
|
|
|
|
The first-wave execution path is:
|
|
|
|
1. create a fresh execution snapshot;
|
|
2. rerun the gate on that snapshot;
|
|
3. materialize outputs from frozen in-memory inputs;
|
|
4. write to `build/.staging/<operation-id>/`;
|
|
5. promote to final `build/` outputs only after coherent success.
|
|
|
|
### 4. Result Semantics
|
|
|
|
The final result must distinguish:
|
|
|
|
- gate failure before emission;
|
|
- execution/materialization failure;
|
|
- persistence/promotion failure;
|
|
- successful publication.
|
|
|
|
Studio should be able to render `Packing` and `Result` from packer-owned outcome semantics alone.
|
|
|
|
## Examples
|
|
|
|
### Example: Why green validation is not enough
|
|
|
|
Validation may have been green a few seconds earlier.
|
|
If the workspace changes before pack execution begins, the packer still must rerun the gate on a fresh frozen snapshot.
|
|
|
|
That protects the operation from:
|
|
|
|
- stale UI assumptions;
|
|
- filesystem drift;
|
|
- accidental emission from no-longer-valid inputs.
|
|
|
|
### Example: Why summary excludes unregistered assets
|
|
|
|
The wizard is a pack-set workflow, not a generic workspace inspection screen.
|
|
Unregistered or excluded assets may matter to other tooling, but they are not explicit summary items in the first-wave wizard contract.
|
|
|
|
## Common Pitfalls and Anti-Patterns
|
|
|
|
- Treating `summary` as if it were an emitted-artifact preview.
|
|
- Running validation over a broader set than `registered + included in build`.
|
|
- Letting non-blocking warnings fail the first-wave validation gate.
|
|
- Reading live filesystem bytes after frozen execution materialization has started.
|
|
- Publishing final `build/` outputs before the operation has reached a coherent success point.
|
|
|
|
## References
|
|
|
|
- Specs:
|
|
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
|
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
|
- Cross-domain:
|
|
- [`../../studio/learn/pack-wizard-shell.md`](../../studio/learn/pack-wizard-shell.md)
|
|
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|