packer (WIP)

This commit is contained in:
2026-03-24 13:42:54 +00:00
parent a57f870217
commit c5b10907c9
4 changed files with 504 additions and 11 deletions
@@ -29,6 +29,13 @@ O estado atual já sugere várias restrições importantes:
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`
@@ -56,6 +63,11 @@ Isso significa que o fluxo precisa ser decidido primeiro e depois propagado para
- 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
@@ -92,7 +104,9 @@ Se tudo passar, fechar esse modal e abrir outro diálogo dedicado só ao progres
Adotar `Option B` como baseline.
O `Pack` deve abrir um wizard modal de workspace, owner do Studio na apresentação e owner do packer na semântica operacional.
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
@@ -112,6 +126,7 @@ 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
@@ -120,6 +135,7 @@ A segunda fase deve executar uma validação explícita sobre os assets incluíd
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`.
@@ -130,14 +146,27 @@ Modelo didático mínimo da tela:
- 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 e orientada a progresso.
Essa fase deve ser não editável, operante e orientada a progresso.
Regras:
@@ -146,6 +175,7 @@ Regras:
- 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:
@@ -153,6 +183,12 @@ Semântica recomendada:
- 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.
@@ -171,14 +207,26 @@ Se houver falha depois de a validação ter passado, a tela final deve diferenci
- 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 com bloqueios agregados por asset;
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;
@@ -186,6 +234,12 @@ O Studio deve orquestrar essas fases no wizard, mas não redefinir:
- 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.
@@ -199,15 +253,16 @@ Direção recomendada:
- `Pack` disponível apenas quando a fase de validação estiver limpa;
- `Close` ou `Done` só ao final, ou em estados seguros de abortar.
## Open Questions
### Resolved In This Agenda Wave
1. O packer deve expor `summary`, `validate` e `pack` como chamadas separadas ou uma única operação com fases internas observáveis?
2. O pack bloqueia apenas por diagnostics `blocking` ou também por certos warnings elevados a gate de build?
3. A amostragem por asset na fase de validação deve mostrar todos os diagnostics do asset ou apenas os bloqueantes por padrão?
4. O wizard deve permitir exportar ou copiar o resumo de falhas para facilitar correção fora do modal?
5. Existe cancelamento real suportado pelo packer durante a fase `Packing`, ou o primeiro wave deve tratar a operação como não cancelável?
6. O resultado final deve listar também os companion artifacts ou isso fica para drill-down secundário?
7. O build set do `Pack` neste fluxo é estritamente `registered + included`, ou existe necessidade futura de variantes de pack profile?
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