packer (WIP)

This commit is contained in:
2026-03-24 13:42:54 +00:00
parent a57f870217
commit c5b10907c9
4 changed files with 504 additions and 11 deletions
@@ -0,0 +1,152 @@
# Pack Wizard Studio Decision Propagation Agenda
## Status
Open
## Purpose
Converge the packer-side discussion required to propagate the Studio `Pack Wizard` decision into packer-owned public contracts.
The immediate goal is not to implement packing behavior yet.
The goal is to close how the packer should expose summary, validation, execution, progress, and result contracts so Studio can remain a shell over packer-owned semantics.
This agenda is driven by the Studio-side decision:
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
## Context
The new Studio decision already closes several boundary rules:
- Studio is a modal shell only;
- packer owns `summary`, `validation`, `pack execution`, progress, and result semantics;
- the wizard has four explicit phases:
`Summary`, `Validation`, `Packing`, `Result`;
- the pack set is the current `registered + included in build` set;
- blocking diagnostics in that set fail validation;
- the first wave is non-cancelable;
- `assets.pa` remains the canonical emitted artifact.
What remains open on the packer side is the exact API and DTO shape that should support this flow cleanly.
Important current constraints:
1. `PackerWorkspaceService` already exposes multiple operation-specific request/response pairs rather than one giant command surface;
2. the public API already has stable patterns for:
- `...Request`
- `...Result`
- `PackerOperationStatus`
- event-driven progress through `PackerEvent` and `PackerProgress`;
3. the build artifact spec already defines `assets.pa` authority and deterministic `asset_table` rules;
4. the Studio decision explicitly requires three distinct calls:
`summary`, `validation`, and `pack execution`.
This means the packer should extend an existing contract style where possible instead of inventing a one-off build wizard protocol.
## Options
### Option A - Three new public operations with dedicated request/result DTOs
Add three explicit public operations to `PackerWorkspaceService`:
1. summary
2. validation
3. pack execution
Each operation gets dedicated request/result messages, with nested DTOs where needed.
Progress continues through the existing event path.
### Option B - One `pack` command plus phase-rich result objects
Expose one public `pack` call and let Studio infer phases from intermediate result payloads and packer events.
Summary and validation would become either optional preflight flags or internal behavior hidden behind one command.
### Option C - Composite build session contract
Create a higher-level `PackSession` or similar build-session API that owns summary, validation, execution, and result under one larger protocol object.
Studio would talk to that session abstraction rather than to simple operation methods.
## Tradeoffs
- Option A matches the existing public API style best and aligns with the Studio decision directly.
- Option A also makes each phase testable and reusable without forcing execution.
- Option A increases DTO count, but the surface stays explicit and predictable.
- Option B reduces top-level API additions, but it hides too much semantic structure from Studio and pushes phase reconstruction into the host.
- Option B also weakens the explicit preflight/value of `summary` and `validation`.
- Option C could become elegant later if the build system grows more modes, but it is too heavy for the current wave and risks introducing a second API style beside the existing `PackerWorkspaceService` request/result pattern.
## Recommendation
Adopt `Option A`.
The packer should expose three explicit public operations and keep them aligned with the existing API style.
Recommended first-wave contract direction:
1. add `PackWorkspaceSummaryRequest` / `PackWorkspaceSummaryResult`;
2. add `ValidatePackWorkspaceRequest` / `ValidatePackWorkspaceResult`;
3. add `PackWorkspaceRequest` / `PackWorkspaceResult`;
4. add focused DTOs for:
- pack summary
- per-asset validation status
- validation aggregate
- emitted artifact summary
- final pack result summary
5. reuse existing public primitives where they already fit:
- `PackerProjectContext`
- `PackerOperationStatus`
- `PackerDiagnosticDTO`
- `PackerProgress`
- existing event publication path for operation progress.
### Boundary Recommendation
The packer contract should state clearly:
- summary is read-oriented and non-mutating;
- validation is dry-run-like and non-emitting;
- pack execution is the only operation that actually emits build artifacts.
### Validation Recommendation
The validation contract should be build-set-scoped and asset-oriented.
It should return at least:
- aggregate counts;
- whether packing is allowed;
- per-asset validation entries for assets in scope;
- blocking diagnostics for default display;
- enough detail for Studio drill-down without local recomputation.
### Execution Recommendation
The execution contract should keep final result summary separate from progress.
Progress should continue to flow through the existing packer event system rather than being duplicated into polling-oriented response DTOs for the first wave.
The final result should describe:
- final status;
- emitted canonical artifact `assets.pa`;
- emitted companion artifacts where available;
- total assets packed;
- duration or equivalent timing summary when available.
## Open Questions
1. Should validation result DTOs include all diagnostics in scope or only the subset relevant to the pack gate by default?
2. Should the final pack result expose artifact paths, artifact labels, or both?
3. Does the first-wave summary contract need companion artifact preview data, or is `assets.pa` plus counts enough before execution?
4. Should the pack execution result carry timing directly, or should timing remain event-derived metadata?
## Expected Follow-up
1. Convert this agenda into a packer `decision` that closes the public API shape.
2. Execute a packer PR that adds the public contracts in `prometeu-packer-api`.
3. Follow with a packer implementation PR in `prometeu-packer-v1` for summary, validation, progress, and pack execution behavior.
4. Follow with a Studio PR to bind the wizard shell to the new packer contracts.
@@ -0,0 +1,107 @@
# 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/**`