108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
# 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/**`
|