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
@@ -0,0 +1,179 @@
# Pack Wizard in Assets Workspace Decision
Status: Decided
Cycle: 2026-03
Domain Owner: `docs/studio`
Cross-Domain Impact: `docs/packer`
## Context
The `Assets` workspace already reserves workspace-level action space for `Pack`, but the Studio did not yet have a closed decision for how that action should behave.
The discussion is not about a button alone.
It is about the operational contract between Studio and packer when a developer wants to pack the current asset build set into `assets.pa`.
The agenda that closed the discussion is:
- [`Pack Wizard in Assets Workspace Agenda.md`](../agendas/Pack%20Wizard%20in%20Assets%20Workspace%20Agenda.md)
Relevant upstream references are:
- [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- [`../../packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`](../../packer/specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
This decision closes the boundary, flow, and first-wave gating rules for the `Pack` wizard.
## Decision
`Pack` in the `Assets` workspace is a Studio-owned modal shell over packer-owned operations.
The first-wave decision is:
1. clicking `Pack` opens a workspace-level modal wizard;
2. the wizard has four explicit phases:
`Summary`, `Validation`, `Packing`, and `Result`;
3. Studio owns presentation, navigation, and state binding for the modal;
4. packer owns summary generation, validation semantics, pack execution, progress, and result semantics;
5. the canonical emitted runtime artifact remains `assets.pa`;
6. the runtime-facing `asset_table` remains packer-owned and deterministic by increasing `asset_id`.
## Operational Contract
The Studio must call three distinct packer operations:
1. `summary`
2. `validation`
3. `pack execution`
These are separate calls, not one opaque long-running operation from the Studio point of view.
The Studio must not start `pack execution` just to obtain summary or validation state.
The packer may share internal implementation between those calls, but the Studio-facing API boundary must preserve the distinction.
## Wizard Flow
### Summary
The `Summary` phase presents the current build set that would be packed.
The minimum summary surface includes:
- count of registered assets included in the current build set;
- count of assets outside the build set;
- explicit mention that the emitted runtime artifact is `assets.pa`;
- explicit mention that `asset_table` ordering follows deterministic `asset_id` ordering.
Studio must not reconstruct the build set locally.
It presents packer-owned summary data.
### Validation
The `Validation` phase is a packer-owned dry-run-like validation over the pack set only.
The pack set for this flow is:
- registered assets;
- included in build.
Validation rules:
1. any blocking diagnostic in that set fails validation;
2. failed validation prevents transition into `Packing`;
3. warnings may be shown, but warnings do not block the first-wave pack unless packer explicitly classifies them as blocking;
4. the validation surface shows blocking diagnostics by default;
5. the developer may inspect additional asset context through drill-down, but the primary goal of the phase is to explain the gate.
This validation is conceptually similar to a restricted deep-sync dry-run, but its scope is only the assets that actually participate in the pack.
### Packing
`Packing` is an operational, non-editable execution phase.
Rules:
1. the phase shows a progress bar and short current-step text;
2. progress must come from packer-owned progress events or structured progress state;
3. the Studio must not fake progress with timers;
4. the modal remains in an operant state until completion or failure;
5. the first wave does not support cancellation;
6. the UI must not present fake or misleading cancel behavior.
### Result
The `Result` phase summarizes the completed operation.
The primary result summary includes:
- final status;
- total assets packed;
- elapsed time;
- explicit reference to `assets.pa`.
Companion artifacts are secondary detail.
They may appear in drill-down or expanded result detail, but they do not dominate the primary result summary.
The result surface must distinguish:
1. validation failure;
2. execution/generation failure;
3. persistence/emission failure.
## Justification
This keeps ownership aligned with the domain model.
Studio is a shell and interaction layer.
Packer is the owner of build-set semantics, diagnostics classification, deterministic output ordering, progress semantics, and final artifact emission.
Using distinct `Summary`, `Validation`, `Packing`, and `Result` phases also makes the flow didactic and operationally honest.
The developer can see what will be packed, why packing is blocked, when the operation is running, and what was emitted at the end.
Keeping validation restricted to `registered + included in build` avoids ambiguity.
The wizard is about packing the active build set, not about re-auditing unrelated assets.
Treating the first wave as non-cancelable is also the correct baseline.
The UI must not imply cancellation guarantees that the packer does not actually provide.
## Invariants and Constraints
The following constraints now apply:
1. `Pack` is a workspace-level action, not a selected-asset action;
2. Studio is not the semantic owner of pack validation or execution;
3. Studio presents packer-owned data and results rather than recomputing them locally;
4. the pack set is the current `registered + included in build` set;
5. blocking diagnostics in that set stop the flow at `Validation`;
6. `Packing` is non-editable and non-cancelable in the first wave;
7. `assets.pa` remains the canonical artifact name in Studio-facing copy and contracts.
## Explicit Non-Decisions
This decision does not yet define:
- the exact packer request and response type names;
- the exact event payload schema for progress and final result;
- whether a future wave should support exporting or copying failure summaries;
- whether a future wave should support real cooperative cancellation;
- the final visual styling of the wizard shell beyond the phase structure and behavior.
## Propagation Targets
- Studio specs:
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Studio plans and code:
the `Assets` workspace action bar, the future pack wizard shell, validation/result surfaces, and progress binding
- Packer plans, specs, and code:
summary API, validation API, pack execution API, progress contract, and result contract for Studio consumption
- Packer build artifacts:
`assets.pa` emission and related companion artifact reporting
## Validation Notes
Examples implied by this decision:
- opening the modal should first request packer-owned summary data rather than locally counting navigator rows;
- if validation reports one included asset with blocking diagnostics, the wizard must remain blocked before `Packing`;
- if packing starts, the modal becomes operational and non-editable until the packer reports completion or failure;
- the primary result summary should mention `assets.pa` even if richer companion artifact details are also available.