packer (WIP)
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user