prometeu-studio/docs/studio/decisions/Pack Wizard in Assets Workspace Decision.md

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

Relevant upstream references are:

• 4. Assets Workspace Specification.md
• ../../packer/specs/4. Build Artifacts and Deterministic Packing Specification.md
• ../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.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
• 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.