prometeu-studio/docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md

PR-29 Pack Wizard Contract Adjustments for Summary and Validation

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

Briefing

The first public contract wave for the Pack Wizard has already landed in prometeu-packer-api, but the newly accepted packer decision for summary and validation closes a more specific shape than the initial API slice.

In particular:

• summary is no longer aggregate-only;
• summary must expose a per-asset list for the active pack set;
• validation is primarily a per-asset blocking-diagnostics list;
• validation ordering is not a packer concern in the first wave;
• aggregate validation data is secondary, not the center of the contract.

This PR adjusts the public contracts so they match the accepted packer decision exactly.

Reference decision:

• ../decisions/Pack Wizard Summary and Validation Contracts Decision.md

Objective

Align the public prometeu-packer-api contract for summary and validation with the accepted decision before deeper implementation work continues.

Dependencies

• ./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md
• ../decisions/Pack Wizard Summary and Validation Contracts Decision.md
• cross-domain reference: ../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md

Scope

• adjust the public summary DTOs to include:
  • aggregate included asset count
  • per-asset summary list
• adjust the public validation DTOs to make the per-asset blocking-diagnostics list the primary payload
• add or rename DTOs as needed for:
  • per-asset summary entry
  • per-asset validation entry
• keep lastModified present in both summary and validation item contracts
• preserve the read-only and non-mutating nature of summary and validation
• keep the Studio-facing API explicit and aligned with the accepted packer decision

Non-Goals

• no runtime implementation of summary in prometeu-packer-v1
• no runtime implementation of validation in prometeu-packer-v1
• no pack execution contract changes unless strictly required by compile compatibility
• no Studio implementation work in this PR

Execution Method

1. Revisit the current summary and validation public DTOs in prometeu-packer-api.
2. Expand the summary result shape so it carries:
   • total included asset count
   • per-asset summary entries
3. Expand or reshape validation so the returned per-asset entries expose:
   • asset id
   • asset name
   • asset path
   • lastModified
   • blocking diagnostics
4. Keep validation aggregate data optional or secondary rather than the primary response focus.
5. Preserve defensive-copy and validation patterns already used by public API records.
6. Update Studio compile surfaces only as needed to keep the workspace consuming the revised contracts coherently.

Acceptance Criteria

• the public summary contract matches the accepted decision shape
• the public validation contract matches the accepted decision shape
• lastModified exists in both per-asset summary and per-asset validation entries
• validation payloads carry blocking diagnostics only in the first wave
• compile succeeds across prometeu-packer-api, prometeu-packer-v1, and any directly affected Studio call sites

Validation

• compile validation for prometeu-packer-api
• compile validation for prometeu-packer-v1
• compile validation for prometeu-studio
• lightweight API tests if public message-shape tests already exist

Affected Artifacts

• docs/packer/decisions/**
• 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/**
• prometeu-studio/** compile-level consumers of the summary/validation contracts