# 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)