# Pack Wizard in Assets Workspace Decision

Status: Decided
Cycle: 2026-03
Domain Owner: `docs/studio`
Cross-Domain Impact: `docs/packer`

## Context

The `Assets` workspace already reserves workspace-level action space for `Pack`, but the Studio did not yet have a closed decision for how that action should behave.

The discussion is not about a button alone.
It is about the operational contract between Studio and packer when a developer wants to pack the current asset build set into `assets.pa`.

The agenda that closed the discussion is:

- [`Pack Wizard in Assets Workspace Agenda.md`](../agendas/Pack%20Wizard%20in%20Assets%20Workspace%20Agenda.md)

Relevant upstream references are:

- [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- [`../../packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`](../../packer/specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)

This decision closes the boundary, flow, and first-wave gating rules for the `Pack` wizard.

## Decision

`Pack` in the `Assets` workspace is a Studio-owned modal shell over packer-owned operations.

The first-wave decision is:

1. clicking `Pack` opens a workspace-level modal wizard;
2. the wizard has four explicit phases:
   `Summary`, `Validation`, `Packing`, and `Result`;
3. Studio owns presentation, navigation, and state binding for the modal;
4. packer owns summary generation, validation semantics, pack execution, progress, and result semantics;
5. the canonical emitted runtime artifact remains `assets.pa`;
6. the runtime-facing `asset_table` remains packer-owned and deterministic by increasing `asset_id`.

## Operational Contract

The Studio must call three distinct packer operations:

1. `summary`
2. `validation`
3. `pack execution`

These are separate calls, not one opaque long-running operation from the Studio point of view.

The Studio must not start `pack execution` just to obtain summary or validation state.

The packer may share internal implementation between those calls, but the Studio-facing API boundary must preserve the distinction.

## Wizard Flow

### Summary

The `Summary` phase presents the current build set that would be packed.

The minimum summary surface includes:

- count of registered assets included in the current build set;
- count of assets outside the build set;
- explicit mention that the emitted runtime artifact is `assets.pa`;
- explicit mention that `asset_table` ordering follows deterministic `asset_id` ordering.

Studio must not reconstruct the build set locally.
It presents packer-owned summary data.

### Validation

The `Validation` phase is a packer-owned dry-run-like validation over the pack set only.

The pack set for this flow is:

- registered assets;
- included in build.

Validation rules:

1. any blocking diagnostic in that set fails validation;
2. failed validation prevents transition into `Packing`;
3. warnings may be shown, but warnings do not block the first-wave pack unless packer explicitly classifies them as blocking;
4. the validation surface shows blocking diagnostics by default;
5. the developer may inspect additional asset context through drill-down, but the primary goal of the phase is to explain the gate.

This validation is conceptually similar to a restricted deep-sync dry-run, but its scope is only the assets that actually participate in the pack.

### Packing

`Packing` is an operational, non-editable execution phase.

Rules:

1. the phase shows a progress bar and short current-step text;
2. progress must come from packer-owned progress events or structured progress state;
3. the Studio must not fake progress with timers;
4. the modal remains in an operant state until completion or failure;
5. the first wave does not support cancellation;
6. the UI must not present fake or misleading cancel behavior.

### Result

The `Result` phase summarizes the completed operation.

The primary result summary includes:

- final status;
- total assets packed;
- elapsed time;
- explicit reference to `assets.pa`.

Companion artifacts are secondary detail.
They may appear in drill-down or expanded result detail, but they do not dominate the primary result summary.

The result surface must distinguish:

1. validation failure;
2. execution/generation failure;
3. persistence/emission failure.

## Justification

This keeps ownership aligned with the domain model.

Studio is a shell and interaction layer.
Packer is the owner of build-set semantics, diagnostics classification, deterministic output ordering, progress semantics, and final artifact emission.

Using distinct `Summary`, `Validation`, `Packing`, and `Result` phases also makes the flow didactic and operationally honest.
The developer can see what will be packed, why packing is blocked, when the operation is running, and what was emitted at the end.

Keeping validation restricted to `registered + included in build` avoids ambiguity.
The wizard is about packing the active build set, not about re-auditing unrelated assets.

Treating the first wave as non-cancelable is also the correct baseline.
The UI must not imply cancellation guarantees that the packer does not actually provide.

## Invariants and Constraints

The following constraints now apply:

1. `Pack` is a workspace-level action, not a selected-asset action;
2. Studio is not the semantic owner of pack validation or execution;
3. Studio presents packer-owned data and results rather than recomputing them locally;
4. the pack set is the current `registered + included in build` set;
5. blocking diagnostics in that set stop the flow at `Validation`;
6. `Packing` is non-editable and non-cancelable in the first wave;
7. `assets.pa` remains the canonical artifact name in Studio-facing copy and contracts.

## Explicit Non-Decisions

This decision does not yet define:

- the exact packer request and response type names;
- the exact event payload schema for progress and final result;
- whether a future wave should support exporting or copying failure summaries;
- whether a future wave should support real cooperative cancellation;
- the final visual styling of the wizard shell beyond the phase structure and behavior.

## Propagation Targets

- Studio specs:
  [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Studio plans and code:
  the `Assets` workspace action bar, the future pack wizard shell, validation/result surfaces, and progress binding
- Packer plans, specs, and code:
  summary API, validation API, pack execution API, progress contract, and result contract for Studio consumption
- Packer build artifacts:
  `assets.pa` emission and related companion artifact reporting

## Validation Notes

Examples implied by this decision:

- opening the modal should first request packer-owned summary data rather than locally counting navigator rows;
- if validation reports one included asset with blocking diagnostics, the wizard must remain blocked before `Packing`;
- if packing starts, the modal becomes operational and non-editable until the packer reports completion or failure;
- the primary result summary should mention `assets.pa` even if richer companion artifact details are also available.
