prometeu-studio/docs/packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md

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

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
• ./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md
• ./PR-19-api-surface-audit-model-separation-and-public-read-dtos.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/**