Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md
bQUARKz 5b6ed046fc
packer (WIP)
2026-03-24 13:42:55 +00:00

10 KiB
Raw Blame History

Pack Wizard Studio Decision Propagation Agenda

Status

Open

Purpose

Converge the packer-side discussion required to propagate the Studio Pack Wizard decision into packer-owned public contracts.

The immediate goal is not to implement packing behavior yet. The goal is to close how the packer should expose summary, validation, execution, progress, and result contracts so Studio can remain a shell over packer-owned semantics.

This agenda is driven by the Studio-side decision:

Context

The new Studio decision already closes several boundary rules:

  • Studio is a modal shell only;
  • packer owns summary, validation, pack execution, progress, and result semantics;
  • the wizard has four explicit phases: Summary, Validation, Packing, Result;
  • the pack set is the current registered + included in build set;
  • blocking diagnostics in that set fail validation;
  • the first wave is non-cancelable;
  • assets.pa remains the canonical emitted artifact.

What remains open on the packer side is the exact API and DTO shape that should support this flow cleanly.

Important current constraints:

  1. PackerWorkspaceService already exposes multiple operation-specific request/response pairs rather than one giant command surface;
  2. the public API already has stable patterns for:
    • ...Request
    • ...Result
    • PackerOperationStatus
    • event-driven progress through PackerEvent and PackerProgress;
  3. the build artifact spec already defines assets.pa authority and deterministic asset_table rules;
  4. the Studio decision explicitly requires three distinct calls: summary, validation, and pack execution.

This means the packer should extend an existing contract style where possible instead of inventing a one-off build wizard protocol.

Options

Option A - Three new public operations with dedicated request/result DTOs

Add three explicit public operations to PackerWorkspaceService:

  1. summary
  2. validation
  3. pack execution

Each operation gets dedicated request/result messages, with nested DTOs where needed.

Progress continues through the existing event path.

Option B - One pack command plus phase-rich result objects

Expose one public pack call and let Studio infer phases from intermediate result payloads and packer events.

Summary and validation would become either optional preflight flags or internal behavior hidden behind one command.

Option C - Composite build session contract

Create a higher-level PackSession or similar build-session API that owns summary, validation, execution, and result under one larger protocol object.

Studio would talk to that session abstraction rather than to simple operation methods.

Tradeoffs

  • Option A matches the existing public API style best and aligns with the Studio decision directly.
  • Option A also makes each phase testable and reusable without forcing execution.
  • Option A increases DTO count, but the surface stays explicit and predictable.
  • Option B reduces top-level API additions, but it hides too much semantic structure from Studio and pushes phase reconstruction into the host.
  • Option B also weakens the explicit preflight/value of summary and validation.
  • Option C could become elegant later if the build system grows more modes, but it is too heavy for the current wave and risks introducing a second API style beside the existing PackerWorkspaceService request/result pattern.

Recommendation

Adopt Option A.

The packer should expose three explicit public operations and keep them aligned with the existing API style.

Recommended first-wave contract direction:

  1. add PackWorkspaceSummaryRequest / PackWorkspaceSummaryResult;
  2. add ValidatePackWorkspaceRequest / ValidatePackWorkspaceResult;
  3. add PackWorkspaceRequest / PackWorkspaceResult;
  4. add focused DTOs for:
    • pack summary
    • per-asset validation status
    • validation aggregate
    • emitted artifact summary
    • final pack result summary
  5. reuse existing public primitives where they already fit:
    • PackerProjectContext
    • PackerOperationStatus
    • PackerDiagnosticDTO
    • PackerProgress
    • existing event publication path for operation progress.

Boundary Recommendation

The packer contract should state clearly:

  • summary is read-oriented and non-mutating;
  • validation is dry-run-like and non-emitting;
  • pack execution is the only operation that actually emits build artifacts.

Validation Recommendation

The validation contract should be build-set-scoped and asset-oriented.

Rules:

  • 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

The execution contract should keep final result summary separate from progress.

Progress should continue to flow through the existing packer event system rather than being duplicated into polling-oriented response DTOs for the first wave.

The final result should describe:

  • final status;
  • emitted canonical artifact assets.pa;
  • emitted companion artifacts where available;
  • 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 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

  1. Convert this agenda into a packer decision that closes the public API shape.
  2. Execute a packer PR that adds the public contracts in prometeu-packer-api.
  3. Follow with a packer implementation PR in prometeu-packer-v1 for summary, validation, progress, and pack execution behavior.
  4. Follow with a Studio PR to bind the wizard shell to the new packer contracts.