# PR-28 Pack Wizard Public Contracts: Summary, Validation, and Execution

Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`

## Briefing

The Studio `Pack Wizard` decision is now closed on the host side.

That decision makes the intended boundary explicit:

- Studio is a shell;
- packer owns summary, validation, pack execution, progress, and result semantics;
- the Studio-facing flow depends on three distinct calls:
  `summary`, `validation`, and `pack execution`.

This PR creates the packer-side public contracts needed for that flow.

Reference decision:

- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)

## Objective

Add public packer contracts for pack summary, pack validation, and pack execution so Studio can bind the wizard flow without inventing local semantics.

## Dependencies

- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
- [`./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md)
- [`./PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md)

## Scope

- extend `PackerWorkspaceService` with three explicit public operations:
  - pack summary
  - pack validation
  - pack execution
- add request/response messages for those operations in `prometeu-packer-api`
- add public DTOs required by those responses
- reuse existing API concepts wherever already adequate instead of cloning parallel concepts
- define result shapes that Studio can bind directly for:
  - `Summary`
  - `Validation`
  - `Result`
- keep progress ownership aligned with the existing event-based packer operational model

## Non-Goals

- no full `prometeu-packer-v1` implementation of summary, validation, or pack execution in this PR
- no Studio wizard implementation in this PR
- no cancellation contract in the first wave
- no speculative build-session abstraction
- no duplication of existing diagnostics DTOs if current public DTOs already satisfy the need

## Execution Method

1. Audit current public API shapes in `prometeu-packer-api` and reuse existing patterns for request/result naming, status, diagnostics, and progress.
2. Extend `PackerWorkspaceService` with three explicit methods that match the Studio decision boundary.
3. Add request/result messages under `p.packer.messages` for:
   - summary
   - validation
   - pack execution
4. Add focused DTOs under the public API for:
   - pack summary aggregate
   - pack validation aggregate
   - pack validation per-asset entry
   - emitted artifact summary
   - final pack execution summary
5. Reuse existing public diagnostics DTOs for validation drill-down where possible.
6. Keep progress delivery on the existing event path instead of embedding a second progress protocol into result DTOs.
7. Keep naming aligned with the canonical artifact terminology `assets.pa`.

## Contract Direction

The new public surface should make these distinctions explicit:

1. summary is read-only preflight information about the current pack set;
2. validation is dry-run-like and non-emitting;
3. pack execution is the only operation that emits artifacts;
4. the pack set is the current `registered + included in build` set;
5. blocking diagnostics in that set make validation unsuccessful.

## Acceptance Criteria

- `PackerWorkspaceService` exposes three distinct public methods for summary, validation, and pack execution
- the public API includes request/result messages for all three operations
- public DTOs exist for the Studio wizard to render summary, validation, and final result
- existing public diagnostics DTOs are reused where appropriate instead of duplicated
- progress remains aligned with the packer event model rather than a new ad hoc progress response shape
- the contract language uses `assets.pa` as the canonical emitted artifact name

## Validation

- compile-level validation that `prometeu-packer-api` exposes the new methods and DTOs coherently
- public API review for naming and reuse consistency
- contract-focused tests if lightweight API tests already exist for public message shapes
- Studio-side binding review to confirm the API is sufficient without local semantic reconstruction

## Affected Artifacts

- `docs/packer/agendas/**`
- `docs/packer/pull-requests/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/PackerWorkspaceService.java`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/dtos/**`