packer (WIP)

This commit is contained in:
2026-03-24 13:42:55 +00:00
parent 66375aaa86
commit 5b6ed046fc
5 changed files with 535 additions and 10 deletions
@@ -0,0 +1,93 @@
# 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`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.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`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
- cross-domain reference:
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../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
@@ -0,0 +1,83 @@
# PR-30 Pack Wizard Summary Snapshot Query
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
With the public contracts aligned, the next step is to actually produce the pack-wizard `summary` from the packer runtime snapshot.
This is intentionally narrower than full pack execution.
The goal is to expose a fast preflight summary of the active pack set so the Studio wizard can open on packer-owned state instead of local UI heuristics.
Reference decision:
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
## Objective
Implement snapshot-backed `summary` for the pack wizard over the current `registered + included in build` set.
## Dependencies
- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
- cross-domain reference:
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
## Scope
- implement `getPackWorkspaceSummary(...)` in `prometeu-packer-v1`
- resolve the active pack set from the runtime snapshot:
`registered + included in build`
- produce the aggregate included asset count
- produce the per-asset summary list with:
- asset id
- asset name
- asset family
- min artifact count
- max artifact count
- `lastModified`
- allow `lastModified = 0` in the first wave where the real value is not yet available
- keep the query fast and snapshot-backed
## Non-Goals
- no validation logic in this PR
- no pack execution logic in this PR
- no emitted-artifact preview in summary
- no inclusion of unregistered or excluded assets as explicit summary items
## Execution Method
1. Resolve the active runtime snapshot for the requested project.
2. Filter the snapshot to the active pack set:
registered assets included in build.
3. Derive one aggregate count from that filtered set.
4. Map each included asset into the public per-asset summary DTO.
5. Populate `minArtifactCount` and `maxArtifactCount` from the best currently available packer-owned summary facts.
6. Populate `lastModified` from packer-owned runtime or filesystem facts when available, otherwise `0`.
7. Return the summary result without performing deep validation or artifact planning.
## Acceptance Criteria
- `getPackWorkspaceSummary(...)` returns successfully from snapshot-backed state
- the returned set contains only `registered + included in build` assets
- the aggregate count matches the per-asset list size
- per-asset summary entries expose the fields required by the accepted decision
- the operation behaves as a fast read query rather than a deep recomputation path
## Validation
- packer unit tests for pack-set filtering
- packer unit tests for summary DTO mapping
- regression tests proving excluded and unregistered assets do not appear as summary items
- Studio smoke validation proving the wizard summary can render from packer-owned data
## Affected Artifacts
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
- `prometeu-studio/**` wizard summary consumer surfaces if compile adaptation is needed
@@ -0,0 +1,91 @@
# PR-31 Pack Wizard Validation Snapshot Gate
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The `Pack Wizard` validation phase is not a generic workspace scan.
It is a pack-set-specific gate over the current `registered + included in build` snapshot state.
The accepted decision closes the first-wave semantics:
- validation is read-only and snapshot-backed;
- validation looks only at the active pack set;
- only `blocking` diagnostics fail validation;
- the primary payload is the per-asset blocking-diagnostics list.
This PR implements that gate in `prometeu-packer-v1`.
Reference decision:
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
## Objective
Implement snapshot-backed pack validation that returns per-asset blocking diagnostics for the active pack set and decides whether packing may proceed.
## Dependencies
- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
- [`./PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md)
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
- cross-domain reference:
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
## Scope
- implement `validatePackWorkspace(...)` in `prometeu-packer-v1`
- evaluate only the current `registered + included in build` set from the runtime snapshot
- collect only `blocking` diagnostics for the first-wave validation payload
- return per-asset validation entries with:
- asset id
- asset name
- asset path
- `lastModified`
- blocking diagnostics
- make validation green when no blocking diagnostics are returned
- make validation red when any blocking diagnostics are returned
- keep aggregate validation data secondary to the per-asset list
## Non-Goals
- no pack execution in this PR
- no non-blocking diagnostics in the first-wave validation payload
- no packer-owned ordering contract for the returned validation list
- no deep-sync orchestration in this PR beyond using the current snapshot boundary
## Execution Method
1. Resolve the current runtime snapshot for the requested project.
2. Filter it to the active pack set:
`registered + included in build`.
3. Gather diagnostics relevant to each asset in that set.
4. Keep only diagnostics marked `blocking` for the first-wave validation response.
5. Map each asset with blockers into the public per-asset validation DTO.
6. Allow `lastModified = 0` temporarily where the real value is not yet available.
7. Return validation as green when the per-asset blocker list is empty and red otherwise.
## Acceptance Criteria
- `validatePackWorkspace(...)` evaluates only the active pack set
- only blocking diagnostics appear in the first-wave validation payload
- validation succeeds when no blocking diagnostics are present
- validation fails when any blocking diagnostics are present
- per-asset validation entries expose the fields required by the accepted decision
- Studio can stop before `Packing` using packer-owned validation alone
## Validation
- packer unit tests for pack-set filtering during validation
- packer unit tests proving non-blocking diagnostics do not fail the first-wave validation
- packer unit tests proving blocking diagnostics do fail validation
- DTO-mapping tests for per-asset validation entries
- Studio smoke validation proving the wizard blocks on returned blockers
## Affected Artifacts
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
- `prometeu-studio/**` validation consumer surfaces if compile adaptation is needed