packer (WIP)
This commit is contained in:
parent
66375aaa86
commit
5b6ed046fc
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -115,13 +115,34 @@ The packer contract should state clearly:
|
||||
|
||||
The validation contract should be build-set-scoped and asset-oriented.
|
||||
|
||||
It should return at least:
|
||||
Rules:
|
||||
|
||||
- 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.
|
||||
- validation runs on the same pack set used by summary:
|
||||
`registered + included in build`;
|
||||
- validation is read-only, non-mutating, and snapshot-backed;
|
||||
- validation may reuse deep inspection or reconcile-grade logic internally;
|
||||
- a future deep-sync step may run before validation in the Studio flow, but validation itself still evaluates the packer snapshot;
|
||||
- only diagnostics marked `blocking` fail validation in the first wave;
|
||||
- if the returned per-asset list contains no blocking diagnostics, validation is green;
|
||||
- if the returned per-asset list contains any blocking diagnostics, validation is red and packing must not begin.
|
||||
|
||||
The first-wave validation payload should prioritize the per-asset diagnostic list over aggregate data.
|
||||
|
||||
Each validation item should expose:
|
||||
|
||||
- asset id;
|
||||
- asset name;
|
||||
- asset path;
|
||||
- `lastModified`;
|
||||
- diagnostics.
|
||||
|
||||
The diagnostics in this contract are blocking diagnostics only in the first wave.
|
||||
|
||||
Aggregate data is secondary here.
|
||||
It may still exist, but it should not be treated as the primary UI payload because the Studio can derive aggregate views from the returned per-asset list if needed.
|
||||
|
||||
Ordering is not a packer concern for the first-wave validation payload.
|
||||
The Studio may sort the returned items as it sees fit.
|
||||
|
||||
### Execution Recommendation
|
||||
|
||||
@ -137,12 +158,75 @@ The final result should describe:
|
||||
- total assets packed;
|
||||
- duration or equivalent timing summary when available.
|
||||
|
||||
### Summary Recommendation
|
||||
|
||||
The first-wave summary contract is now closed as a fast snapshot-backed preflight view.
|
||||
|
||||
Rules:
|
||||
|
||||
- summary is read-only and non-mutating;
|
||||
- summary must return quickly from packer-owned snapshot state rather than from a deep recomputation pass;
|
||||
- packer is the only source of truth for the summary;
|
||||
- Studio must not reconstruct the summary from local navigator state;
|
||||
- unregistered assets and excluded assets do not appear as explicit summary items;
|
||||
- the summary does not anticipate emitted artifacts, companion artifacts, or `assets.pa` details in the first wave.
|
||||
|
||||
The first-wave summary shape should contain:
|
||||
|
||||
1. one aggregate count for the current pack set;
|
||||
2. one per-asset list for the current pack set.
|
||||
|
||||
The aggregate is intentionally minimal in the first wave:
|
||||
|
||||
- total included asset count is enough for now.
|
||||
|
||||
Each per-asset summary entry should include at least:
|
||||
|
||||
- asset name;
|
||||
- asset family;
|
||||
- min artifact count for that asset;
|
||||
- max artifact count for that asset;
|
||||
- `lastModified` as a `long`.
|
||||
|
||||
`lastModified` is explicitly useful even if the packer cannot yet provide the final real value for every asset in the first implementation wave.
|
||||
The contract may expose `0` temporarily, but the field should already exist so the Studio can depend on the shape and later sort against real values.
|
||||
|
||||
This per-asset list is the correct place for the developer-facing graphical occupancy preview per asset in the Studio shell.
|
||||
The aggregate should remain intentionally small.
|
||||
|
||||
## 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?
|
||||
1. Should the final pack result expose artifact paths, artifact labels, or both?
|
||||
2. Should the pack execution result carry timing directly, or should timing remain event-derived metadata?
|
||||
|
||||
## Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed for `summary`:
|
||||
|
||||
1. summary is read-only, non-mutating, and snapshot-backed;
|
||||
2. packer is the sole source of truth for summary data;
|
||||
3. unregistered and excluded assets do not appear as explicit summary entries;
|
||||
4. first-wave summary includes one aggregate count only:
|
||||
total included asset count;
|
||||
5. first-wave summary also includes a per-asset list for the current pack set;
|
||||
6. each per-asset summary entry must expose:
|
||||
asset name, asset family, min artifact count, max artifact count, and `lastModified`;
|
||||
7. `lastModified` may temporarily be `0` until full support exists, but the field should already exist in the public contract;
|
||||
8. summary does not anticipate companion artifacts or emitted artifact details in the first wave.
|
||||
|
||||
The following points are now closed for `validation`:
|
||||
|
||||
1. validation runs on the same `registered + included in build` set used by summary;
|
||||
2. validation is read-only, non-mutating, and snapshot-backed;
|
||||
3. only diagnostics marked `blocking` fail validation in the first wave;
|
||||
4. the primary validation payload is the per-asset diagnostics list, not the aggregate;
|
||||
5. each per-asset validation entry must expose:
|
||||
asset id, asset name, asset path, `lastModified`, and diagnostics;
|
||||
6. the diagnostics returned by validation are blocking diagnostics only in the first wave;
|
||||
7. if the returned validation list contains no blocking diagnostics, validation is green;
|
||||
8. if the returned validation list contains any blocking diagnostics, validation is red and packing must not begin;
|
||||
9. payload ordering is not a packer responsibility in the first wave;
|
||||
10. a future deep-sync step may be added before validation in the Studio flow, but validation itself still evaluates the packer snapshot.
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
|
||||
@ -0,0 +1,174 @@
|
||||
# Pack Wizard Summary and Validation Contracts Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-20
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Context
|
||||
|
||||
The Studio `Pack Wizard` flow is now closed on the host side as a shell over packer-owned operations.
|
||||
|
||||
That decision already fixed the outer boundary:
|
||||
|
||||
- Studio is the shell;
|
||||
- packer owns summary, validation, pack execution, progress, and result semantics;
|
||||
- the wizard flow is phase-based;
|
||||
- the active pack set is the current `registered + included in build` set.
|
||||
|
||||
On the packer side, the first remaining need is to close the public contract for `summary` and `validation` before the repository moves deeper into pack execution semantics.
|
||||
|
||||
This decision consolidates the `summary` and `validation` part of the packer-side discussion from:
|
||||
|
||||
- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
|
||||
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
|
||||
The main question is not whether Studio should have these phases.
|
||||
That is already settled.
|
||||
The question is what the packer must expose as the authoritative public contract for those phases.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer public contract for the `Pack Wizard` first wave adopts the following direction:
|
||||
|
||||
1. `summary` and `validation` are distinct packer operations;
|
||||
2. both operations are read-only and non-mutating;
|
||||
3. both operations evaluate the same pack set:
|
||||
`registered + included in build`;
|
||||
4. both operations are packer-owned and snapshot-backed;
|
||||
5. Studio consumes these packer responses and must not reconstruct equivalent semantics locally.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Summary Boundary
|
||||
|
||||
- `summary` is a fast snapshot-backed preflight view;
|
||||
- `summary` must return from packer-owned snapshot state, not from a deep recomputation pass;
|
||||
- `summary` is not a build preview and must not imply that artifacts were emitted;
|
||||
- `summary` must not anticipate companion artifacts or emitted artifact details in the first wave;
|
||||
- `summary` must not include unregistered assets or excluded assets as explicit summary items.
|
||||
|
||||
### 2. Summary Shape
|
||||
|
||||
The first-wave `summary` contract contains:
|
||||
|
||||
1. one aggregate count for the active pack set;
|
||||
2. one per-asset list for the active pack set.
|
||||
|
||||
The aggregate is intentionally minimal in the first wave:
|
||||
|
||||
- total included asset count is sufficient.
|
||||
|
||||
Each per-asset summary entry must expose:
|
||||
|
||||
- `assetId`
|
||||
- `assetName`
|
||||
- `assetFamily`
|
||||
- `minArtifactCount`
|
||||
- `maxArtifactCount`
|
||||
- `lastModified`
|
||||
|
||||
`lastModified` is required in the public contract even if early implementations temporarily expose `0` until the real value is fully available per asset.
|
||||
|
||||
The per-asset summary list is the intended payload for Studio-side graphical occupancy presentation.
|
||||
The aggregate remains deliberately small.
|
||||
|
||||
### 3. Validation Boundary
|
||||
|
||||
- `validation` evaluates the same active pack set as `summary`;
|
||||
- `validation` is read-only and non-mutating;
|
||||
- `validation` is snapshot-backed;
|
||||
- `validation` may internally reuse deep-inspection or reconcile-grade logic where needed;
|
||||
- a future Studio flow may add an explicit deep-sync step before validation, but validation itself still evaluates the packer snapshot boundary.
|
||||
|
||||
### 4. Validation Failure Rule
|
||||
|
||||
Only diagnostics marked `blocking` fail validation in the first wave.
|
||||
|
||||
The rule is:
|
||||
|
||||
- if no blocking diagnostics are returned for the active pack set, validation is green;
|
||||
- if any blocking diagnostics are returned for the active pack set, validation is red and packing must not begin.
|
||||
|
||||
Warnings and non-blocking diagnostics are not part of the first-wave validation gate contract.
|
||||
|
||||
### 5. Validation Shape
|
||||
|
||||
The primary validation payload is the per-asset diagnostics list.
|
||||
|
||||
Aggregate validation data may still exist, but it is secondary.
|
||||
The Studio may derive aggregate visual summaries from the per-asset list if useful.
|
||||
|
||||
Each per-asset validation entry must expose:
|
||||
|
||||
- `assetId`
|
||||
- `assetName`
|
||||
- `assetPath`
|
||||
- `lastModified`
|
||||
- `diagnostics`
|
||||
|
||||
In the first wave, `diagnostics` in this contract means blocking diagnostics only.
|
||||
|
||||
Ordering is not a packer responsibility in the first-wave validation payload.
|
||||
The Studio may sort the returned list as needed for presentation.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It keeps `summary` and `validation` aligned with the existing request/result API style instead of inventing a special build-session protocol too early.
|
||||
- It keeps ownership where it belongs: the packer remains the source of truth for pack-set semantics and validation outcomes.
|
||||
- It gives Studio enough structured data to render the preflight and validation phases without recreating packer meaning.
|
||||
- It keeps the first-wave contract intentionally narrow so the repository can close `summary` and `validation` without prematurely locking the heavier `pack execution` semantics.
|
||||
- It gives the Studio enough per-asset detail to show useful occupancy and blocker views while keeping ordering and higher-level UI grouping on the host side.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the final `pack execution` request/result contract;
|
||||
- emitted artifact reporting rules beyond what is already upstream in packer artifact specs;
|
||||
- the final event vocabulary for pack progress;
|
||||
- whether future validation payloads should include non-blocking diagnostics;
|
||||
- the final source for real `lastModified` values in every asset case;
|
||||
- runtime-ingestion and cartridge-facing conformance gates for actual artifact emission.
|
||||
|
||||
## Implications
|
||||
|
||||
- the current public API work for pack summary must expand beyond aggregate-only shape;
|
||||
- the current public API work for validation must expand beyond generic aggregate-first DTOs;
|
||||
- Studio `Pack Wizard` binding should evolve toward the per-asset summary and per-asset validation payloads defined here;
|
||||
- `summary` and `validation` can now be implemented independently of the heavier pack execution discussion;
|
||||
- the next packer discussion wave should focus primarily on execution semantics, artifact emission guarantees, and runtime/cartridge ingestion conformance.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- [`../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
||||
|
||||
Cross-domain references:
|
||||
|
||||
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
- [`../../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)
|
||||
|
||||
Implementation surfaces:
|
||||
|
||||
- `prometeu-packer-api` summary and validation request/result DTOs
|
||||
- snapshot-backed pack summary query logic
|
||||
- snapshot-backed pack validation logic
|
||||
- Studio pack wizard summary and validation bindings
|
||||
|
||||
## Validation Notes
|
||||
|
||||
This decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- `summary` returns quickly from packer-owned snapshot state;
|
||||
- Studio does not reconstruct pack summary from navigator rows or local UI state;
|
||||
- `summary` returns only active pack-set items, not excluded or unregistered items;
|
||||
- `validation` returns blocking-diagnostic information per asset for the same active pack set;
|
||||
- a returned validation payload with any blocking diagnostics stops the wizard before pack execution;
|
||||
- the Studio may reorder the returned lists without changing packer semantics.
|
||||
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user