packer (WIP)
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user