Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md
bQUARKz 0e5e1669c2
clean up
2026-03-24 13:42:57 +00:00

4.0 KiB
Raw Blame History

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