prometeu-studio/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md

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:

• ../../studio/decisions/Pack Wizard in Assets Workspace Decision.md

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.

It should return at least:

• 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.

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.

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?

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.