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
@@ -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