prometeu-studio/docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md

Pack Wizard Summary and Validation Contracts Decision

Status: Accepted Date: 2026-03-20 Domain Owner: docs/packer Cross-Domain Impact: docs/studio

Context

The Studio Pack Wizard flow is now closed on the host side as a shell over packer-owned operations.

That decision already fixed the outer boundary:

• Studio is the shell;
• packer owns summary, validation, pack execution, progress, and result semantics;
• the wizard flow is phase-based;
• the active pack set is the current registered + included in build set.

On the packer side, the first remaining need is to close the public contract for summary and validation before the repository moves deeper into pack execution semantics.

This decision consolidates the summary and validation part of the packer-side discussion from:

• ../agendas/Pack Wizard Studio Decision Propagation Agenda.md
• ../../studio/decisions/Pack Wizard in Assets Workspace Decision.md

The main question is not whether Studio should have these phases. That is already settled. The question is what the packer must expose as the authoritative public contract for those phases.

Decision

The packer public contract for the Pack Wizard first wave adopts the following direction:

1. summary and validation are distinct packer operations;
2. both operations are read-only and non-mutating;
3. both operations evaluate the same pack set: registered + included in build;
4. both operations are packer-owned and snapshot-backed;
5. Studio consumes these packer responses and must not reconstruct equivalent semantics locally.

Adopted Constraints

1. Summary Boundary

• summary is a fast snapshot-backed preflight view;
• summary must return from packer-owned snapshot state, not from a deep recomputation pass;
• summary is not a build preview and must not imply that artifacts were emitted;
• summary must not anticipate companion artifacts or emitted artifact details in the first wave;
• summary must not include unregistered assets or excluded assets as explicit summary items.

2. Summary Shape

The first-wave summary contract contains:

1. one aggregate count for the active pack set;
2. one per-asset list for the active pack set.

The aggregate is intentionally minimal in the first wave:

• total included asset count is sufficient.

Each per-asset summary entry must expose:

• assetId
• assetName
• assetFamily
• minArtifactCount
• maxArtifactCount
• lastModified

lastModified is required in the public contract even if early implementations temporarily expose 0 until the real value is fully available per asset.

The per-asset summary list is the intended payload for Studio-side graphical occupancy presentation. The aggregate remains deliberately small.

3. Validation Boundary

• validation evaluates the same active pack set as summary;
• validation is read-only and non-mutating;
• validation is snapshot-backed;
• validation may internally reuse deep-inspection or reconcile-grade logic where needed;
• a future Studio flow may add an explicit deep-sync step before validation, but validation itself still evaluates the packer snapshot boundary.

4. Validation Failure Rule

Only diagnostics marked blocking fail validation in the first wave.

The rule is:

• if no blocking diagnostics are returned for the active pack set, validation is green;
• if any blocking diagnostics are returned for the active pack set, validation is red and packing must not begin.

Warnings and non-blocking diagnostics are not part of the first-wave validation gate contract.

5. Validation Shape

The primary validation payload is the per-asset diagnostics list.

Aggregate validation data may still exist, but it is secondary. The Studio may derive aggregate visual summaries from the per-asset list if useful.

Each per-asset validation entry must expose:

• assetId
• assetName
• assetPath
• lastModified
• diagnostics

In the first wave, diagnostics in this contract means blocking diagnostics only.

Ordering is not a packer responsibility in the first-wave validation payload. The Studio may sort the returned list as needed for presentation.

Why This Direction Was Chosen

• It keeps summary and validation aligned with the existing request/result API style instead of inventing a special build-session protocol too early.
• It keeps ownership where it belongs: the packer remains the source of truth for pack-set semantics and validation outcomes.
• It gives Studio enough structured data to render the preflight and validation phases without recreating packer meaning.
• It keeps the first-wave contract intentionally narrow so the repository can close summary and validation without prematurely locking the heavier pack execution semantics.
• It gives the Studio enough per-asset detail to show useful occupancy and blocker views while keeping ordering and higher-level UI grouping on the host side.

Explicit Non-Decisions

This decision does not yet define:

• the final pack execution request/result contract;
• emitted artifact reporting rules beyond what is already upstream in packer artifact specs;
• the final event vocabulary for pack progress;
• whether future validation payloads should include non-blocking diagnostics;
• the final source for real lastModified values in every asset case;
• runtime-ingestion and cartridge-facing conformance gates for actual artifact emission.

Implications

• the current public API work for pack summary must expand beyond aggregate-only shape;
• the current public API work for validation must expand beyond generic aggregate-first DTOs;
• Studio Pack Wizard binding should evolve toward the per-asset summary and per-asset validation payloads defined here;
• summary and validation can now be implemented independently of the heavier pack execution discussion;
• the next packer discussion wave should focus primarily on execution semantics, artifact emission guarantees, and runtime/cartridge ingestion conformance.

Propagation Targets

Specs:

• ../specs/4. Build Artifacts and Deterministic Packing Specification.md
• ../specs/5. Diagnostics, Operations, and Studio Integration Specification.md

Plans:

• ../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md

Cross-domain references:

• ../../studio/decisions/Pack Wizard in Assets Workspace Decision.md
• ../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md

Implementation surfaces:

• prometeu-packer-api summary and validation request/result DTOs
• snapshot-backed pack summary query logic
• snapshot-backed pack validation logic
• Studio pack wizard summary and validation bindings

Validation Notes

This decision is correctly implemented only when all of the following are true:

• summary returns quickly from packer-owned snapshot state;
• Studio does not reconstruct pack summary from navigator rows or local UI state;
• summary returns only active pack-set items, not excluded or unregistered items;
• validation returns blocking-diagnostic information per asset for the same active pack set;
• a returned validation payload with any blocking diagnostics stops the wizard before pack execution;
• the Studio may reorder the returned lists without changing packer semantics.