prometeu-studio/docs/studio/agendas/Pack Wizard in Assets Workspace Agenda.md

# Pack Wizard in Assets Workspace Agenda

Status: Open
Domain Owner: `docs/studio`
Cross-Domain Impact: `docs/packer`

## Problem

O workspace `Assets` já reserva a action area para `Pack`, mas ainda não existe uma discussão fechada sobre o fluxo exato desse comando no Studio.

O pedido atual não é apenas adicionar um botão.
O `Pack` precisa abrir um modal que funcione como wizard operacional do empacotador e deixe claro:

- o resumo do que será empacotado;
- a validação obrigatória antes do build;
- a regra de bloqueio quando existirem diagnostics em assets incluídos;
- o progresso da geração do artefato;
- e o resumo final do resultado.

Sem essa agenda, há risco de misturar decisão de UX com semântica de packer e de implementar um modal visualmente correto, mas operacionalmente fraco.

## Context

O estado atual já sugere várias restrições importantes:

1. o `Assets` workspace define `Pack` como ação global de workspace, não como ação do asset selecionado;
2. a spec do Studio já separa `Pack` do fluxo de staged mutations sensíveis;
3. a spec do packer define `assets.pa` como artefato runtime autoritativo, com `asset_table` determinística e baseada apenas nos assets incluídos no build set atual;
4. o packer já trata diagnostics como parte do modelo operacional, então o Studio não deve inventar uma semântica paralela de validação;
5. o usuário precisa de feedback de progresso e de falha com drill-down por asset, não apenas logs.

Boundary baseline desta agenda:

- o Studio é casca operacional;
- o Studio chama serviços do packer, observa progresso e apresenta estado;
- o trabalho bruto de summary, validation, packing e result pertence ao packer;
- o Studio não deve reimplementar regras de build, gating ou ordenação.

Artefatos e referências já relevantes:

- `docs/studio/specs/4. Assets Workspace Specification.md`
- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
- `docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md`

Nota de nomenclatura:

- a spec vigente usa `assets.pa` como nome canônico do artefato;
- esta agenda deve seguir `assets.pa`, mesmo que a conversa operacional use `asset.pa` informalmente.

## Current Code Context

O contexto atual no código Studio é suficiente para ancorar a discussão:

- o botão `Pack` foi introduzido na action bar do workspace em `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`;
- o workspace já possui região inline de progresso, painel de logs e integração com eventos do packer;
- ainda não existe wizard de pack nem API explícita de `pack` em `PackerWorkspaceService`.

Isso significa que o fluxo precisa ser decidido primeiro e depois propagado para:

- contrato da API do packer;
- eventos operacionais de progresso;
- modelagem de resultado;
- e shell/modal do Studio.

Leitura operacional explícita:

- o wizard é Studio-owned apenas como shell de interação;
- a semântica do pack é packer-owned ponta a ponta.

## Options

### Option A - Single modal with one primary action

Abrir um modal com resumo inicial e um único botão `Pack`.
Ao confirmar, o Studio valida, empacota e mostra sucesso ou falha no mesmo corpo, sem etapas explícitas de wizard.

### Option B - Multi-step wizard with explicit operational phases

Abrir um wizard com fases claras:

1. `Summary`
2. `Validation`
3. `Packing`
4. `Result`

Cada fase deixa explícito o estado operacional atual e evita que o usuário perca contexto entre bloqueio, execução e resultado.

### Option C - Split flow with preflight modal plus separate progress dialog

Abrir um modal curto para resumo e validação.
Se tudo passar, fechar esse modal e abrir outro diálogo dedicado só ao progresso e resultado do pack.

## Tradeoffs

- Option A é mais rápida de implementar, mas colapsa estados diferentes demais em uma única superfície e tende a virar um modal ambíguo.
- Option A também dificulta explicar por que o pack foi bloqueado e o que exatamente falhou por asset.
- Option B exige mais estrutura de estado, mas deixa o fluxo didático, previsível e alinhado ao pedido de wizard empacotador.
- Option B também facilita mapear cada fase para contratos distintos do packer: preflight, validação, execução e resultado.
- Option C separa bem responsabilidades visuais, mas fragmenta a experiência e pode parecer que o usuário saiu de um fluxo para entrar em outro.
- Option C ainda aumenta o custo de coordenação de foco, fechamento e recuperação de erro.

## Recommendation

Adotar `Option B` como baseline.

O `Pack` deve abrir um wizard modal de workspace.
O Studio é owner apenas da apresentação e navegação do modal.
O packer é owner da semântica operacional, da validação, da execução e do resultado.

### Recommended Flow

#### 1. Summary

O wizard abre em um resumo do build atual.
Esse resumo deve mostrar pelo menos:

- quantidade de assets registrados e incluídos no build atual;
- quantidade de assets excluídos ou fora do build set;
- indicação de que o output canônico será `assets.pa`;
- indicação de que a `asset_table` seguirá a ordem determinística por `asset_id`, conforme spec;
- artefatos companion previstos quando aplicável.

Regras:

- assets não incluídos no build não entram no pack;
- assets não registrados também não entram no pack;
- o resumo deve deixar explícito que a operação trabalha sobre o build set atual, não sobre todo o workspace.
- o Studio apenas apresenta esse resumo; ele não recompõe localmente o build set.

#### 2. Validation

A segunda fase deve executar uma validação explícita sobre os assets incluídos no build.

Baseline recomendado:

- qualquer diagnostic bloqueante em asset incluído falha a validação e impede o início do pack;
- a validação deve ser tratada como processo packer-owned semelhante a um `deep sync` dry-run, mas restrito ao conjunto `registered + included in build`;
- a tela deve mostrar resumo agregado e amostragem por asset do que falhou;
- a UI deve permitir drill-down por asset sem despejar log cru como explicação principal;
- se houver warnings não bloqueantes, eles podem ser exibidos, mas não devem impedir o `Pack`.

Modelo didático mínimo da tela:

- topo com contagem de assets validados, aprovados e bloqueados;
- lista por asset com status;
- ao selecionar ou expandir um asset, mostrar diagnostics relevantes daquele asset.

Baseline fechado nesta agenda wave:

- a fase de validação mostra diagnostics bloqueantes por padrão;
- a tela deve permitir que o developer inspecione contexto adicional quando necessário;
- esse drill-down adicional não muda o foco principal da fase, que é explicar o gate de bloqueio.

A responsabilidade pela classificação do que bloqueia ou não deve permanecer no packer.
O Studio apenas consome e apresenta essa classificação.

Direção mais precisa para esta agenda:

- a validação não é uma checagem local do Studio;
- a validação é uma operação explícita do packer;
- ela reutiliza a lógica de reconciliação/inspeção profunda necessária para afirmar se o build set atual pode ser empacotado;
- mas seu escopo é apenas o conjunto de assets que realmente participariam do pack.

#### 3. Packing

Se a validação passar, o wizard entra em fase de execução.

Essa fase deve ser não editável, operante e orientada a progresso.

Regras:

- mostrar barra de progresso com atualização contínua;
- mostrar texto curto da etapa atual;
- manter o usuário no mesmo modal até conclusão, falha ou cancelamento suportado por contrato;
- deixar explícito que o pack está montando `assets.pa` e a `asset_table` conforme as specs vigentes;
- logs detalhados podem existir em área secundária, mas não substituem o indicador principal de progresso.
- durante `Packing`, o wizard não deve expor affordances de edição ou revisão que façam a operação parecer reversível ou parcialmente configurável.

Semântica recomendada:

- o packer expõe eventos ou snapshots de progresso por operação;
- o Studio mapeia isso para uma barra de progresso e rótulos humanos;
- o wizard não deve inferir progresso a partir de timers artificiais.

Baseline fechado para a primeira versão:

- não há cancelamento durante `Packing`;
- o modal permanece em estado operante até conclusão ou falha;
- a UI não deve simular cancelamento sem suporte cooperativo real do packer.

#### 4. Result

Ao concluir, o wizard deve mostrar um resumo final do resultado.

O resumo deve cobrir:

- status final: sucesso parcial ou falha;
- quantidade de assets efetivamente empacotados;
- artefatos emitidos;
- duração da operação;
- falhas ou avisos finais, quando existirem.

Se houver falha depois de a validação ter passado, a tela final deve diferenciar:

- falha de validação;
- falha de execução/geração;
- e falha de persistência/emissão.

Baseline fechado nesta agenda wave:

- o resumo principal prioriza `assets.pa`, duração e total de assets empacotados;
- companion artifacts ficam em drill-down secundário;
- os diagnostics do resultado tendem a já existir nos assets e não precisam dominar a superfície principal.

### Contract Direction

Para a próxima onda de decisão, o contrato recomendado é separar pelo menos três responsabilidades no packer:

1. `preflight summary` do build set atual;
2. `validation` do build set como dry-run packer-owned semelhante a `deep sync`, com bloqueios agregados por asset;
3. `pack execution` com progresso estruturado e resultado final.

Baseline fechado nesta agenda wave:

- `summary`, `validation` e `pack execution` são chamadas distintas;
- o Studio não deve iniciar `pack execution` para conseguir `summary` ou `validation`;
- a separação deve permanecer visível na API consumida pelo Studio.

O Studio deve orquestrar essas fases no wizard, mas não redefinir:

- quais assets entram no build set;
- o que conta como diagnostic bloqueante;
- a ordem da `asset_table`;
- ou o que exatamente compõe `assets.pa`.

Em termos práticos:

- o Studio chama;
- o packer decide;
- o Studio mostra.

### UI Direction

O wizard deve ser operacional, não um formulário tradicional.

Direção recomendada:

- stepper simples no topo ou lateral;
- corpo central com conteúdo da fase;
- ações de navegação controladas pelo estado operacional;
- `Next` bloqueado quando a validação falhar;
- `Pack` disponível apenas quando a fase de validação estiver limpa;
- `Close` ou `Done` só ao final, ou em estados seguros de abortar.

### Resolved In This Agenda Wave

Os seguintes pontos ficam fechados como baseline para a próxima `decision`:

1. `summary`, `validation` e `pack execution` são chamadas distintas.
2. A validação mostra diagnostics bloqueantes por padrão e permite inspeção adicional para o developer.
3. A primeira versão não suporta cancelamento durante `Packing`.
4. Companion artifacts ficam em drill-down secundário no resultado final.
5. A primeira versão não exporta nem copia o resumo de falhas.
6. Pode existir um botão `dumb` na UI como lembrete explícito de feature futura, sem comportamento operacional no `v1`.

## Suggested Next Step

O próximo passo correto é converter esta agenda em uma `decision` owner de `docs/studio`, com propagação explícita para `docs/packer`.

Essa decision deve fechar:

1. o shape do wizard e suas fases;
2. o gate de validação baseado em diagnostics dos assets incluídos;
3. o contrato mínimo de API/eventos que o packer precisa expor para suportar o wizard;
4. a distinção entre falha de validação e falha de execução;
5. o vocabulário canônico do resultado final em torno de `assets.pa` e `asset_table`.

Depois disso, o trabalho deve ser decomposto em pelo menos dois planos:

1. um `PR/plan` em `docs/packer` para summary, validation, pack execution, progress e result contract;
2. um `PR/plan` em `docs/studio` para shell do wizard, fases, binding de progresso e tela de resultado.