Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity

packer (WIP)

Browse Source
This commit is contained in:
bQUARKz 2026-03-19 17:52:44 +00:00
parent a57f870217
commit c5b10907c9
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
4 changed files with 504 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md Normal file
View File

@ -0,0 +1,152 @@
# 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`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.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.

107
docs/packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md Normal file
View File

@ -0,0 +1,107 @@
# PR-28 Pack Wizard Public Contracts: Summary, Validation, and Execution
Domain Owner: `docs/packer`
Cross-Domain Impact: `docs/studio`
## Briefing
The Studio `Pack Wizard` decision is now closed on the host side.
That decision makes the intended boundary explicit:
- Studio is a shell;
- packer owns summary, validation, pack execution, progress, and result semantics;
- the Studio-facing flow depends on three distinct calls:
`summary`, `validation`, and `pack execution`.
This PR creates the packer-side public contracts needed for that flow.
Reference decision:
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
## Objective
Add public packer contracts for pack summary, pack validation, and pack execution so Studio can bind the wizard flow without inventing local semantics.
## Dependencies
- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
- [`./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md)
- [`./PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md)
## Scope
- extend `PackerWorkspaceService` with three explicit public operations:
- pack summary
- pack validation
- pack execution
- add request/response messages for those operations in `prometeu-packer-api`
- add public DTOs required by those responses
- reuse existing API concepts wherever already adequate instead of cloning parallel concepts
- define result shapes that Studio can bind directly for:
- `Summary`
- `Validation`
- `Result`
- keep progress ownership aligned with the existing event-based packer operational model
## Non-Goals
- no full `prometeu-packer-v1` implementation of summary, validation, or pack execution in this PR
- no Studio wizard implementation in this PR
- no cancellation contract in the first wave
- no speculative build-session abstraction
- no duplication of existing diagnostics DTOs if current public DTOs already satisfy the need
## Execution Method
1. Audit current public API shapes in `prometeu-packer-api` and reuse existing patterns for request/result naming, status, diagnostics, and progress.
2. Extend `PackerWorkspaceService` with three explicit methods that match the Studio decision boundary.
3. Add request/result messages under `p.packer.messages` for:
- summary
- validation
- pack execution
4. Add focused DTOs under the public API for:
- pack summary aggregate
- pack validation aggregate
- pack validation per-asset entry
- emitted artifact summary
- final pack execution summary
5. Reuse existing public diagnostics DTOs for validation drill-down where possible.
6. Keep progress delivery on the existing event path instead of embedding a second progress protocol into result DTOs.
7. Keep naming aligned with the canonical artifact terminology `assets.pa`.
## Contract Direction
The new public surface should make these distinctions explicit:
1. summary is read-only preflight information about the current pack set;
2. validation is dry-run-like and non-emitting;
3. pack execution is the only operation that emits artifacts;
4. the pack set is the current `registered + included in build` set;
5. blocking diagnostics in that set make validation unsuccessful.
## Acceptance Criteria
- `PackerWorkspaceService` exposes three distinct public methods for summary, validation, and pack execution
- the public API includes request/result messages for all three operations
- public DTOs exist for the Studio wizard to render summary, validation, and final result
- existing public diagnostics DTOs are reused where appropriate instead of duplicated
- progress remains aligned with the packer event model rather than a new ad hoc progress response shape
- the contract language uses `assets.pa` as the canonical emitted artifact name
## Validation
- compile-level validation that `prometeu-packer-api` exposes the new methods and DTOs coherently
- public API review for naming and reuse consistency
- contract-focused tests if lightweight API tests already exist for public message shapes
- Studio-side binding review to confirm the API is sufficient without local semantic reconstruction
## Affected Artifacts
- `docs/packer/agendas/**`
- `docs/packer/pull-requests/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/PackerWorkspaceService.java`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**`
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/dtos/**`

77
docs/studio/agendas/Pack Wizard in Assets Workspace Agenda.md
View File

@ -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

179
docs/studio/decisions/Pack Wizard in Assets Workspace Decision.md Normal file
View File

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