diff --git a/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md b/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md index 194c8cab..b91a4945 100644 --- a/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md +++ b/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md @@ -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 diff --git a/docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md b/docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md new file mode 100644 index 00000000..81da6e4c --- /dev/null +++ b/docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md @@ -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. diff --git a/docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md b/docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md new file mode 100644 index 00000000..3a17e1b2 --- /dev/null +++ b/docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md @@ -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 diff --git a/docs/packer/pull-requests/PR-30-pack-wizard-summary-snapshot-query.md b/docs/packer/pull-requests/PR-30-pack-wizard-summary-snapshot-query.md new file mode 100644 index 00000000..f6403912 --- /dev/null +++ b/docs/packer/pull-requests/PR-30-pack-wizard-summary-snapshot-query.md @@ -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 diff --git a/docs/packer/pull-requests/PR-31-pack-wizard-validation-snapshot-gate.md b/docs/packer/pull-requests/PR-31-pack-wizard-validation-snapshot-gate.md new file mode 100644 index 00000000..135e1771 --- /dev/null +++ b/docs/packer/pull-requests/PR-31-pack-wizard-validation-snapshot-gate.md @@ -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