180 lines
7.3 KiB
Markdown
180 lines
7.3 KiB
Markdown
# 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.
|