clean up
This commit is contained in:
parent
d16a987949
commit
0e5e1669c2
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -98,10 +98,15 @@ The preferred packer documentation flow is:
|
||||
|
||||
- `agendas/` stores currently open questions only.
|
||||
- `decisions/` stores only decisions that still need propagation.
|
||||
- `pull-requests/` stores execution plans.
|
||||
- `pull-requests/` stores only execution plans for pending work.
|
||||
- `specs/` stores the normative packer contract.
|
||||
- `learn/` stores teaching-oriented consolidation.
|
||||
|
||||
The current packer core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
|
||||
The current packer core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/).
|
||||
At this moment:
|
||||
|
||||
- `agendas/` retains only topics that are still open;
|
||||
- `decisions/` is empty because the last accepted wave was fully propagated;
|
||||
- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`.
|
||||
|
||||
If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`.
|
||||
|
||||
@ -1,295 +0,0 @@
|
||||
# Pack Wizard Studio Decision Propagation Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Purpose
|
||||
|
||||
Converge the packer-side discussion that still remains open after the first `Pack Wizard` propagation wave: the actual `packing` operation.
|
||||
|
||||
`summary` and `validation` are already closed enough to implement and consume.
|
||||
What is still unresolved is how `pack execution` should behave as a packer-owned operation when Studio enters the `Packing` and `Result` phases.
|
||||
|
||||
This agenda is therefore about execution semantics, artifact emission, progress visibility, and failure boundaries for `packWorkspace(...)`.
|
||||
|
||||
## Problem
|
||||
|
||||
The repository already closed the Studio shell boundary and the packer-side preflight boundary, but the actual pack execution contract is still underspecified.
|
||||
|
||||
Today the gap is concrete:
|
||||
|
||||
1. Studio already depends on a four-phase wizard:
|
||||
`Summary`, `Validation`, `Packing`, `Result`;
|
||||
2. the public packer API already exposes `packWorkspace(...)`;
|
||||
3. `prometeu-packer-v1` still throws `UnsupportedOperationException` for that operation;
|
||||
4. the specs define `assets.pa` authority and deterministic ordering, but they do not yet define the operational semantics for emitting that artifact through the Studio-facing service boundary.
|
||||
|
||||
Without this agenda, implementation risks falling into one of these traps:
|
||||
|
||||
- a direct file-write implementation that leaks partial artifacts;
|
||||
- a Studio-visible progress model that is too vague to support the wizard honestly;
|
||||
- an execution path that does not clearly separate validation failure from emission failure;
|
||||
- or a result contract that is too poor for the `Result` phase even if the pack technically succeeds.
|
||||
|
||||
## Context
|
||||
|
||||
The upstream state is now clear enough to isolate the remaining question.
|
||||
|
||||
Already closed:
|
||||
|
||||
- Studio is a shell over packer-owned semantics:
|
||||
[`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
- packer-side `summary` and `validation` contracts are accepted:
|
||||
[`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
|
||||
- runtime artifact authority is already normative:
|
||||
[`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- event causality and serialized operation rules are already normative:
|
||||
[`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
Current code context:
|
||||
|
||||
- `getPackWorkspaceSummary(...)` already exists in `FileSystemPackerWorkspaceService`;
|
||||
- `validatePackWorkspace(...)` already exists in `FileSystemPackerWorkspaceService`;
|
||||
- `packWorkspace(...)` exists in the public API but is not implemented in `prometeu-packer-v1`;
|
||||
- the current `PackWorkspaceResult` shape is minimal, but the operational meaning of its fields is not fully closed.
|
||||
|
||||
That means the current decision gap is no longer about whether packing should exist.
|
||||
It is about what guarantees `packWorkspace(...)` must provide when it starts emitting runtime-facing artifacts.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Direct in-place pack with minimal lifecycle semantics
|
||||
|
||||
Implement `packWorkspace(...)` as one serialized write-lane operation that:
|
||||
|
||||
- optionally reruns the validation gate;
|
||||
- emits `assets.pa` and companion artifacts directly into their final locations;
|
||||
- publishes a small number of lifecycle events;
|
||||
- returns one final result DTO with success or failure.
|
||||
|
||||
### Option B - Staged pack transaction with explicit lifecycle phases
|
||||
|
||||
Implement `packWorkspace(...)` as one serialized packer-owned execution flow with explicit internal phases:
|
||||
|
||||
1. gate
|
||||
2. plan/materialize
|
||||
3. stage emit
|
||||
4. commit/promote
|
||||
5. finalize result
|
||||
|
||||
The operation still appears to Studio as one `packWorkspace(...)` call, but the packer gives stronger semantics:
|
||||
|
||||
- validation is rechecked at execution start;
|
||||
- emitted files are staged before final promotion;
|
||||
- final artifact visibility changes only at commit;
|
||||
- progress events map to meaningful lifecycle boundaries;
|
||||
- the final result distinguishes validation, emission, and persistence failure classes.
|
||||
|
||||
### Option C - Detached build session abstraction
|
||||
|
||||
Introduce a larger `PackSession`-style model or resumable build-session protocol for packing.
|
||||
|
||||
Studio would create a session, observe step state, and then explicitly finalize or close it.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
- Option A is the smallest implementation step, but it leaves too many failure and visibility rules implicit.
|
||||
- Option A also makes it easier to leak partially written artifacts into final paths if the process fails mid-pack.
|
||||
- Option B fits the existing service boundary while still making artifact visibility and progress semantics explicit.
|
||||
- Option B also aligns well with the current specs:
|
||||
serialized writes, causal events, deterministic outputs, and packer-owned truth.
|
||||
- Option B adds some implementation structure, but that structure corresponds to real operational risk and is not ceremonial.
|
||||
- Option C could become attractive later if the build system needs cancellation, resume, remote workers, or richer host orchestration.
|
||||
- Option C is too heavy for the current repository state and would introduce a second interaction model before the first one is stable.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt `Option B`.
|
||||
|
||||
The packer should keep `packWorkspace(...)` as a single public service operation, but internally define and honor explicit execution phases with staged emission and an atomic final visibility boundary.
|
||||
|
||||
### Execution Boundary Recommendation
|
||||
|
||||
`packWorkspace(...)` should be the only first-wave operation that emits build artifacts.
|
||||
|
||||
Rules:
|
||||
|
||||
- it runs through the packer-owned serialized write lane for the project;
|
||||
- it evaluates the active pack set as `registered + included in build`;
|
||||
- it must perform an internal gate check before emitting artifacts, even if Studio already ran `validation`;
|
||||
- it must freeze the execution input set before materialization begins;
|
||||
- a failing gate returns a terminal result without creating final artifacts.
|
||||
|
||||
This avoids trusting host orchestration timing as if it were a correctness guarantee.
|
||||
|
||||
### Frozen Snapshot Recommendation
|
||||
|
||||
`packWorkspace(...)` should not pack from live filesystem rereads after execution begins.
|
||||
|
||||
Recommended first-wave baseline:
|
||||
|
||||
- the packer creates a frozen pack-execution snapshot before materialization starts;
|
||||
- that frozen snapshot is derived from the current runtime snapshot but enriches build-relevant walk files with in-memory content bytes;
|
||||
- content bytes are needed only for:
|
||||
- registered assets included in build;
|
||||
- artifact files that actually participate in the current build output;
|
||||
- non-build assets and non-selected artifact files do not need in-memory content in the pack-execution snapshot;
|
||||
- the current runtime snapshot model should expose file bytes as optional rather than introducing a second snapshot model in the first wave;
|
||||
- `PackerRuntimeWalkFile` should therefore carry optional content bytes so the packer can freeze build-relevant inputs without forcing all runtime-backed reads to retain content unnecessarily;
|
||||
- the family walkers may continue to produce full file probes with bytes loaded during probe processing;
|
||||
- the variation for runtime versus packing should happen when probe results are exported into the runtime walk projection;
|
||||
- walker materialization must therefore gain clearer execution context/config so build-focused flows can request content bytes intentionally instead of coupling that behavior to every normal read path.
|
||||
|
||||
This preserves precision without turning the general runtime snapshot into a blanket in-memory mirror of the workspace.
|
||||
|
||||
### Walker Policy Recommendation
|
||||
|
||||
The current walker baseline should remain family-oriented and generalist.
|
||||
|
||||
Recommended first-wave baseline:
|
||||
|
||||
- family walkers continue to discover files relevant to the asset family;
|
||||
- that family-oriented discovery remains the normal runtime-backed mode;
|
||||
- packing adds one extra selection layer instead of redefining walker discovery itself;
|
||||
- the extra selection layer filters the discovered probe results down to the files that actually participate in the current build output;
|
||||
- the same export layer also decides whether optional content bytes are injected into `PackerRuntimeWalkFile`.
|
||||
|
||||
This means the first-wave split should be:
|
||||
|
||||
1. family-relevant probe discovery in the walkers;
|
||||
2. export/materialization policy for runtime projection;
|
||||
3. packing-specific projection filter over discovered probe results;
|
||||
4. optional byte injection only when the export policy requests it.
|
||||
|
||||
This is intentionally conservative.
|
||||
It keeps the walkers on known ground and moves the packing-specific behavior into one explicit projection/materialization policy layer.
|
||||
|
||||
Recommended config shape:
|
||||
|
||||
```java
|
||||
public record PackerRuntimeMaterializationConfig(
|
||||
PackerWalkMode mode,
|
||||
Predicate<PackerProbeResult> projectionFilter) {
|
||||
|
||||
public static PackerRuntimeMaterializationConfig runtimeDefault() {
|
||||
return new PackerRuntimeMaterializationConfig(PackerWalkMode.RUNTIME, probe -> true);
|
||||
}
|
||||
|
||||
public static PackerRuntimeMaterializationConfig packingBuild() {
|
||||
return new PackerRuntimeMaterializationConfig(
|
||||
PackerWalkMode.PACKING,
|
||||
PackerProbePolicies::isIncludedInCurrentBuild);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With this baseline:
|
||||
|
||||
- `PackerWalkMode.RUNTIME` means runtime-backed general projection and suppresses optional content bytes during export;
|
||||
- `PackerWalkMode.PACKING` means packing-focused projection and injects optional content bytes during export;
|
||||
- `projectionFilter` decides which discovered probe results actually survive into `PackerRuntimeWalkFile`;
|
||||
- the first-wave packing filter should keep only current-build probe results;
|
||||
- byte injection behavior is derived from `mode` rather than from a second explicit boolean in the first wave.
|
||||
|
||||
### Emission Recommendation
|
||||
|
||||
Artifact emission should be staged before promotion into final visible locations.
|
||||
|
||||
Recommended first-wave baseline:
|
||||
|
||||
- materialize `assets.pa` and companion artifacts in a staging location owned by the packer operation;
|
||||
- use `build/.staging/<operation-id>/` as the first-wave staging location;
|
||||
- `<operation-id>` should be one random 20-character alphanumeric identifier;
|
||||
- if a staging directory collision happens for that identifier, the packer may overwrite that staging directory rather than adding a second collision-resolution protocol in the first wave;
|
||||
- treat staging output as non-authoritative until commit;
|
||||
- promote staged files into final `build/` locations only after the operation reaches a coherent success point;
|
||||
- if emission fails before commit, final artifact locations must remain unchanged from the caller's point of view.
|
||||
|
||||
This is the safest baseline for a filesystem-first packer.
|
||||
It keeps durable visibility aligned with a packer-owned commit boundary rather than with incidental file-write timing.
|
||||
|
||||
### Progress Recommendation
|
||||
|
||||
Progress should continue to flow through the existing packer event path rather than through a polling-specific result shape.
|
||||
|
||||
The first-wave lifecycle should be observable through summaries and progress updates equivalent to:
|
||||
|
||||
1. `packing_started`
|
||||
2. `packing_validating`
|
||||
3. `packing_materializing`
|
||||
4. `packing_emitting`
|
||||
5. `packing_finalizing`
|
||||
6. terminal success or failure
|
||||
|
||||
The exact event kind names can still be finalized in the decision, but the meaning must be explicit enough for Studio to render the `Packing` phase honestly without fake timers or inferred state.
|
||||
|
||||
### Result Recommendation
|
||||
|
||||
The final `PackWorkspaceResult` should stay compact but semantically explicit.
|
||||
|
||||
The primary result summary should expose at least:
|
||||
|
||||
- final status;
|
||||
- whether validation failed or execution actually began;
|
||||
- canonical build-relative `assets.pa` artifact reference;
|
||||
- build-relative companion artifact references when emitted;
|
||||
- total packed asset count;
|
||||
- elapsed time in milliseconds.
|
||||
|
||||
The first-wave `Result` phase in Studio does not need a full build report dump, but it does need enough structure to distinguish successful pack, blocked pack, and failed pack after execution started.
|
||||
|
||||
### Failure Recommendation
|
||||
|
||||
The packer should distinguish at least three terminal classes:
|
||||
|
||||
1. validation gate failure before emission;
|
||||
2. execution or materialization failure during pack generation;
|
||||
3. persistence or promotion failure while making artifacts final.
|
||||
|
||||
These classes matter because they map directly to the Studio `Result` phase already decided upstream.
|
||||
|
||||
### Build Output Recommendation
|
||||
|
||||
The packer publication boundary for this flow should remain `build/`.
|
||||
|
||||
Recommended first-wave baseline:
|
||||
|
||||
- `packWorkspace(...)` publishes final outputs to `build/`;
|
||||
- the canonical runtime-facing artifact is `build/assets.pa`;
|
||||
- the baseline companion artifacts are:
|
||||
- `build/asset_table.json`
|
||||
- `build/preload.json`
|
||||
- `build/asset_table_metadata.json`
|
||||
- a future shipper may consume those packer outputs together with `program.pbx`;
|
||||
- the shipper is mentioned here only to keep the boundary explicit, not because it participates in `packWorkspace(...)`.
|
||||
|
||||
This keeps the current domain boundary intact:
|
||||
the packer publishes build artifacts and the shipper assembles cartridges.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None for the first-wave execution shape.
|
||||
The remaining work is to convert this agenda into a decision and then propagate the agreed materialization policy into code and specs.
|
||||
|
||||
## Recommendation Summary
|
||||
|
||||
This agenda recommends closing the first-wave `packing` contract as:
|
||||
|
||||
1. one packer-owned `packWorkspace(...)` operation;
|
||||
2. internally phased and serialized through the project write lane;
|
||||
3. guarded by a packer-owned validation check at execution start;
|
||||
4. based on one frozen in-memory execution snapshot for the build-relevant asset bytes;
|
||||
5. staged under `build/.staging/<operation-id>/` before promotion to final artifact visibility in `build/`;
|
||||
6. observable through causality-preserving progress events;
|
||||
7. finished with a result that distinguishes blocked, failed, and successful pack outcomes.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Convert this agenda into a `docs/packer` decision focused on `pack execution` semantics and propagation targets.
|
||||
|
||||
That decision should then drive:
|
||||
|
||||
1. one PR for `prometeu-packer-api` result and event-contract adjustments, if needed;
|
||||
2. one PR for `prometeu-packer-v1` execution, staging, and artifact-promotion behavior;
|
||||
3. one Studio PR to bind the `Packing` and `Result` phases to the final packer-owned execution contract.
|
||||
@ -5,11 +5,9 @@ This directory contains active packer discussion agendas.
|
||||
## Active Agendas
|
||||
|
||||
1. [`Tilemap and Metatile Runtime Binary Layout Agenda.md`](./Tilemap%20and%20Metatile%20Runtime%20Binary%20Layout%20Agenda.md)
|
||||
2. [`Pack Wizard Studio Decision Propagation Agenda.md`](./Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
|
||||
3. [`Tile Bank Packing Materialization Agenda.md`](./Tile%20Bank%20Packing%20Materialization%20Agenda.md)
|
||||
4. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md)
|
||||
2. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md)
|
||||
|
||||
The first packer agenda wave was consolidated into normative specs under [`../specs/`](../specs/) and didactic material under [`../learn/`](../learn/).
|
||||
Closed packer agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue.
|
||||
|
||||
## Purpose
|
||||
|
||||
|
||||
@ -1,258 +0,0 @@
|
||||
# Tile Bank Packing Materialization Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `../runtime`, `docs/studio`
|
||||
|
||||
## Purpose
|
||||
|
||||
Convergir a discussão sobre como um asset `tile bank` deve ser materializado durante o `packing` para produzir payload runtime-facing válido dentro de `assets.pa`.
|
||||
|
||||
Esta agenda não trata do workflow operacional do `Pack Wizard`.
|
||||
Ela trata do contrato técnico de materialização do formato `TILES/indexed_v1`:
|
||||
|
||||
- quais arquivos entram no pack;
|
||||
- como eles viram payload binário final;
|
||||
- quais campos do `asset_table` são derivados;
|
||||
- quais metadados convergem para `AssetEntry.metadata`;
|
||||
- e quais invariantes devem falhar o build.
|
||||
|
||||
## Problem
|
||||
|
||||
O repositório já tem base suficiente para:
|
||||
|
||||
1. descobrir arquivos relevantes de `tile bank`;
|
||||
2. validar metadados mínimos como `tile_size`;
|
||||
3. construir snapshots runtime-backed;
|
||||
4. definir `assets.pa` como artefato autoritativo do runtime.
|
||||
|
||||
Mas ainda não existe decisão formal sobre a materialização final de `tile bank` no pack.
|
||||
|
||||
Hoje falta fechar, pelo menos:
|
||||
|
||||
- qual é o payload binário efetivamente emitido para um `tile bank`;
|
||||
- como múltiplos artifacts selecionados são agregados no payload final;
|
||||
- como `bank_type`, `codec`, `size`, `decoded_size` e `metadata` são derivados para a entrada runtime;
|
||||
- quais dados ficam em `AssetEntry.metadata` versus quais permanecem detalhe interno de pipeline;
|
||||
- quais condições tornam o pack inválido para esse formato.
|
||||
|
||||
Sem isso, o `packWorkspace(...)` pode até ganhar semântica operacional correta, mas ainda ficará sem contrato suficiente para produzir `assets.pa` conformat para `tile bank`.
|
||||
|
||||
## Context
|
||||
|
||||
O contrato upstream já impõe limites claros:
|
||||
|
||||
- `assets.pa` é o artefato runtime-facing autoritativo:
|
||||
[`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- `asset_table` é determinística por `asset_id`, offsets são relativos ao payload region e metadata converge para um sink único:
|
||||
[`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- o runtime espera `assets.pa` autocontido com `asset_table` e `preload` válidos:
|
||||
[`../../../runtime/docs/runtime/specs/13-cartridge.md`](../../../runtime/docs/runtime/specs/13-cartridge.md)
|
||||
- o runtime consome `AssetEntry { asset_id, asset_name, bank_type, offset, size, decoded_size, codec, metadata }`:
|
||||
[`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
|
||||
Contexto atual de código:
|
||||
|
||||
- `PackerAssetWalker` já reconhece `OutputFormatCatalog.TILES_INDEXED_V1`;
|
||||
- `PackerTileBankWalker` já produz probes/metadata family-relevant;
|
||||
- o snapshot atual já consegue expor arquivos candidatos e metadata de walk;
|
||||
- ainda não existe materialização final de payload de `tile bank` dentro de `assets.pa`.
|
||||
|
||||
Consumer baseline now confirmed in `../runtime`:
|
||||
|
||||
- `TILES` now uses `codec = NONE` as the runtime-facing v1 baseline;
|
||||
- serialized tile pixels are packed `u4` palette indices in payload order;
|
||||
- the runtime expands those packed indices into one `u8` logical index per pixel in memory after decode;
|
||||
- tile-bank palettes are serialized as `RGB565` `u16` values in little-endian order;
|
||||
- runtime-facing v1 uses `64` palettes per tile bank;
|
||||
- the runtime loader currently requires the following metadata fields for tile banks:
|
||||
- `tile_size`
|
||||
- `width`
|
||||
- `height`
|
||||
- `palette_count`
|
||||
- for v1, `palette_count` must be `64`;
|
||||
- for v1, the serialized tile-bank payload is:
|
||||
1. packed indexed pixels for the full sheet, using `ceil(width * height / 2)` bytes;
|
||||
2. one palette block of `64 * 16 * 2 = 2048` bytes;
|
||||
- for v1, the runtime-side size expectations are:
|
||||
- `size = ceil(width * height / 2) + 2048`
|
||||
- `decoded_size = (width * height) + 2048`
|
||||
- for the producer-side contract discussed here, `tile_id = 0` remains valid and must not be reserved away by the packer.
|
||||
|
||||
Relevant confirmed runtime references:
|
||||
|
||||
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
|
||||
- [`../../../runtime/crates/console/prometeu-drivers/src/asset.rs`](../../../runtime/crates/console/prometeu-drivers/src/asset.rs)
|
||||
- [`../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs`](../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs)
|
||||
- tilemap empty-cell semantics remain under active runtime discussion and must not currently force the packer to reserve `tile_id = 0`:
|
||||
[`../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md`](../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md)
|
||||
|
||||
Isso significa que o problema agora não é descoberta de arquivos.
|
||||
O lado consumidor já está suficientemente claro.
|
||||
O problema agora é fechar o contrato produtor `tile bank -> runtime asset entry + payload bytes` no packer sem contradizer esse baseline runtime.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Concatenate selected tile artifacts as a simple raw stream
|
||||
|
||||
Cada artifact selecionado do `tile bank` vira um segmento binário simples, e o payload final do asset é a concatenação determinística desses segmentos.
|
||||
|
||||
`metadata` carrega apenas o mínimo necessário para o runtime interpretar o asset.
|
||||
|
||||
### Option B - Emit one canonical tile-bank payload plus normalized runtime metadata
|
||||
|
||||
Os artifacts selecionados são primeiro normalizados para um modelo canônico de `tile bank`, e então o packer emite:
|
||||
|
||||
- um único payload binário canônico para o asset;
|
||||
- um conjunto fechado de campos runtime-facing em `AssetEntry.metadata`.
|
||||
|
||||
Qualquer detalhe interno adicional de pipeline fica fora do contrato runtime principal ou vai apenas para tooling metadata.
|
||||
|
||||
### Option C - Preserve rich per-artifact structure directly in runtime metadata
|
||||
|
||||
O packer mantém estrutura mais rica de artifacts individuais no próprio `AssetEntry.metadata`, expondo para o runtime detalhes mais próximos da pipeline de build.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
- Option A é a implementação mais simples, mas corre risco de deixar semântica demais implícita no consumidor.
|
||||
- Option A também pode dificultar compatibilidade futura se a concatenação simples não codificar claramente limites, forma lógica ou derivação de `decoded_size`.
|
||||
- Option B exige fechar um modelo canônico do `tile bank`, mas produz o contrato mais limpo entre packer e runtime.
|
||||
- Option B também respeita melhor a regra já vigente de convergência para `AssetEntry.metadata` sem transformar metadata runtime em espelho da pipeline.
|
||||
- Option C pode parecer flexível no curto prazo, mas mistura detalhe de pipeline com contrato runtime e aumenta acoplamento.
|
||||
- Option C tensiona diretamente o guardrail já documentado de que `asset_table[].metadata` não deve virar depósito arbitrário de estrutura interna.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adotar `Option B`.
|
||||
|
||||
O primeiro formato de packing a ser fechado deve ter payload canônico e metadata runtime-facing normalizada.
|
||||
|
||||
### Payload Recommendation
|
||||
|
||||
O `tile bank` deve produzir um payload binário único por asset incluído no build.
|
||||
|
||||
Regras recomendadas:
|
||||
|
||||
- o payload é derivado apenas dos artifacts selecionados que realmente entram no build atual;
|
||||
- a ordem de agregação dos artifacts deve ser determinística by `artifacts[*].index`;
|
||||
- for v1, `1 artifact = 1 tile`;
|
||||
- for the current target, the canonical tile-bank sheet is always `256 x 256`;
|
||||
- tile placement inside that fixed sheet is row-major;
|
||||
- `tile_id` is the linear row-major slot and therefore matches the normalized `artifacts[*].index`;
|
||||
- resulting capacity is therefore:
|
||||
- `tile_size = 8` -> `32 x 32 = 1024` tiles
|
||||
- `tile_size = 16` -> `16 x 16 = 256` tiles
|
||||
- `tile_size = 32` -> `8 x 8 = 64` tiles
|
||||
- o payload final do asset deve ter fronteiras e interpretação definidas pelo próprio contrato do formato, não por convenção incidental de concatenação;
|
||||
- para `TILES/indexed_v1`, o payload v1 já deve assumir:
|
||||
1. plano de pixels packed `u4`;
|
||||
2. bloco de paletas `64 * 16 * u16`;
|
||||
- palettes must always be materialized to `RGB565` during pack emission;
|
||||
- `size` deve representar o tamanho emitido no payload region;
|
||||
- `decoded_size` deve seguir a convenção runtime já confirmada:
|
||||
tamanho expandido dos indices em memória mais o bloco de paletas runtime-facing.
|
||||
|
||||
### Runtime Entry Recommendation
|
||||
|
||||
Cada `tile bank` emitido para o runtime deve preencher, no mínimo:
|
||||
|
||||
- `asset_id`
|
||||
- `asset_name`
|
||||
- `bank_type = TILES`
|
||||
- `offset`
|
||||
- `size`
|
||||
- `decoded_size`
|
||||
- `codec`
|
||||
- `metadata`
|
||||
|
||||
O contrato de `bank_type`, `codec` e `decoded_size` não deve ser deixado implícito no packer implementation detail.
|
||||
|
||||
Baseline now fixed by the runtime consumer:
|
||||
|
||||
- `bank_type = TILES`
|
||||
- `codec = NONE`
|
||||
- metadata mínima obrigatória:
|
||||
- `tile_size`
|
||||
- `width`
|
||||
- `height`
|
||||
- `palette_count = 64`
|
||||
- `width` and `height` are bank-sheet helpers, not per-artifact dimensions
|
||||
- with the current v1 target, the emitted bank sheet is fixed at `256 x 256`
|
||||
- producer-side metadata normalization must emit what the consumer requires while preserving segmented authoring meaning:
|
||||
- `asset.json.output.metadata` -> `AssetEntry.metadata`
|
||||
- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
|
||||
- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
|
||||
|
||||
### Metadata Recommendation
|
||||
|
||||
`AssetEntry.metadata` deve receber apenas os campos runtime-consumable e format-relevant.
|
||||
|
||||
Direção inicial recomendada:
|
||||
|
||||
- metadados declarativos como `tile_size` entram no sink runtime;
|
||||
- metadados derivados necessários para leitura correta do runtime entram no sink runtime, pelo menos:
|
||||
- `width`
|
||||
- `height`
|
||||
- `palette_count`;
|
||||
- `AssetEntry.metadata` should aggregate normalized maps using this structure:
|
||||
- `asset.json.output.metadata` -> `metadata`
|
||||
- `asset.json.output.codec_configuration` -> `metadata.codec`
|
||||
- `asset.json.output.pipeline` -> `metadata.pipeline`
|
||||
- bank palettes are declared in `asset.json.output.pipeline.palettes` using explicit `{ index, palette }` entries and emitted in ascending numeric `index` order;
|
||||
- any tile in the bank may be rendered with any palette in the bank;
|
||||
- palette assignment is therefore not a per-artifact packing contract and remains a runtime draw-time concern;
|
||||
- the packer must nevertheless validate whether the declared bank palette set safely covers the indices used by packed tiles.
|
||||
- detalhes de pipeline úteis apenas para inspeção e tooling não devem dominar `AssetEntry.metadata`;
|
||||
- quando um detalhe interno for necessário apenas para tooling, ele deve preferir companion tooling data em vez de inflar o contrato runtime.
|
||||
|
||||
### Failure Recommendation
|
||||
|
||||
O build de `tile bank` deve falhar quando qualquer uma das seguintes condições acontecer:
|
||||
|
||||
1. não existir conjunto suficiente de artifacts selecionados para materialização válida;
|
||||
2. o metadata declarativo obrigatório do formato estiver ausente ou inválido;
|
||||
3. a normalização dos artifacts para o payload canônico falhar;
|
||||
4. houver colisão ou ambiguidade ao convergir metadata runtime-facing;
|
||||
5. o packer não conseguir derivar de forma determinística os campos exigidos para a entry runtime.
|
||||
|
||||
Additional first-wave diagnostic expectations:
|
||||
|
||||
- duplicate `artifacts[*].index` is `blocking`;
|
||||
- gap in normalized `artifacts[*].index` ordering is `blocking`;
|
||||
- sheet-capacity overflow for the fixed `256 x 256` target is `blocking`;
|
||||
- bank without declared palettes in `asset.json.output.pipeline.palettes` is `blocking`;
|
||||
- declared palette list above `64` is `blocking`;
|
||||
- malformed palette declarations are `blocking`;
|
||||
- tiles that use fragile indices, meaning indices not represented safely across the full declared bank palette set, emit a `WARNING`;
|
||||
- that fragile-index warning is advisory in the first wave and does not block pack by itself unless later promoted by decision.
|
||||
|
||||
### Packing Boundary Recommendation
|
||||
|
||||
O seletor de packing para `tile bank` deve operar sobre os probes já descobertos pelo walker family-oriented.
|
||||
|
||||
Regras:
|
||||
|
||||
- o walker continua generalista e orientado à family;
|
||||
- a seleção do que entra no payload final acontece na policy/materialization layer de packing;
|
||||
- somente probes do asset registrado, incluído no build, e efetivamente selecionados pelo contrato do formato entram na materialização final;
|
||||
- quando o `PackerRuntimeMaterializationConfig` estiver em `PACKING`, esses probes relevantes devem carregar bytes opcionais preenchidos para congelar o input do pack.
|
||||
- palette declarations in `asset.json.output.pipeline.palettes` carry explicit semantic identity through `index`;
|
||||
- palette order is ascending numeric `index`, never raw array position;
|
||||
- palette ids are the normalized declared `index` values from that pipeline palette list;
|
||||
- all tiles in the bank may use any palette declared in the bank;
|
||||
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. None at this stage for the tile-bank v1 producer contract.
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
1. Converter esta agenda em uma `decision` de `docs/packer` para materialização de `tile bank`.
|
||||
2. Propagar o contrato resultante para:
|
||||
- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
- specs runtime relevantes em `../runtime`
|
||||
3. Planejar PR de implementação do materializador de `tile bank` em `prometeu-packer-v1`.
|
||||
4. Adicionar testes de conformance do formato:
|
||||
`artifacts -> payload -> asset_table entry -> runtime-read assumptions`.
|
||||
@ -1,130 +0,0 @@
|
||||
# Concurrency, Observability, and Studio Adapter Boundary Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-11
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Context
|
||||
|
||||
The production `prometeu-packer` track introduces two architectural seams that must not remain implicit:
|
||||
|
||||
1. the packer will become the operational source of truth for asset summaries, diagnostics, mutation previews, and build lifecycle state;
|
||||
2. Studio will consume that operational model through adapters instead of reconstructing packer semantics locally;
|
||||
3. the event and concurrency model must stay coherent when the packer is integrated into the Studio `Assets` workspace and shell.
|
||||
|
||||
Without an explicit decision, the repository risks drifting into duplicated semantics:
|
||||
|
||||
- Studio deriving packer-facing summaries from filesystem heuristics;
|
||||
- Studio inventing lifecycle meaning not present in packer events;
|
||||
- concurrent mutation or build behavior becoming observable in inconsistent ways.
|
||||
|
||||
## Decision
|
||||
|
||||
The following direction is adopted:
|
||||
|
||||
1. `prometeu-packer` is the semantic owner of asset operational state.
|
||||
2. Studio is a consumer and remapper of packer responses and events, not a competing source of packer truth.
|
||||
3. The baseline packer write policy is a `single-writer semantic lane per project`.
|
||||
4. Packer observability is packer-native and causality-preserving.
|
||||
5. Studio adapters may reshape packer data for UI presentation, but may not invent packer semantics, causal relationships, or final outcomes absent from packer responses/events.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Summary and Response Authority
|
||||
|
||||
- asset `summary`, `details`, `diagnostics`, `preview`, and build/mutation lifecycle state originate in the packer;
|
||||
- Studio may use packer responses directly or remap them into view models;
|
||||
- Studio must not define an alternative packer summary model from direct filesystem inspection once the packer-backed path exists;
|
||||
- UI-oriented phrasing or grouping is allowed only as a remapping of packer-owned semantics.
|
||||
|
||||
### 2. Concurrency Model
|
||||
|
||||
- coordination is project-scoped;
|
||||
- unrelated projects are not forced into one global execution lane;
|
||||
- `read/read` may run concurrently when reads observe a coherent snapshot;
|
||||
- `read/write` must not expose torn intermediate state;
|
||||
- `write/write` on the same project is serialized;
|
||||
- `build/write` on the same project is serialized unless a future explicit transactional model supersedes this baseline;
|
||||
- preview generation may run outside the final commit-critical section when safe, but final apply/commit remains serialized.
|
||||
|
||||
### 3. Event and Observability Model
|
||||
|
||||
- the packer emits the authoritative event stream for asset operations;
|
||||
- each logical operation must carry a stable `operation_id`;
|
||||
- events within one operation must carry monotonic `sequence`;
|
||||
- baseline event payloads must preserve fields equivalent to:
|
||||
- `project_id`
|
||||
- `operation_id`
|
||||
- `sequence`
|
||||
- `kind`
|
||||
- `timestamp`
|
||||
- `summary`
|
||||
- `progress` when applicable
|
||||
- `affected_assets` when applicable
|
||||
- event ordering must remain causally coherent for one operation;
|
||||
- progress-like low-value repetition may be coalesced by sinks/adapters;
|
||||
- terminal lifecycle markers must remain individually observable.
|
||||
|
||||
### 4. Studio Adapter Boundary
|
||||
|
||||
- Studio adapts packer events into the existing Studio event bus and workspace models;
|
||||
- Studio may convert packer-native envelopes into Studio-native event types for shell/workspace consumption;
|
||||
- that adapter layer must remain translational, not semantic-authoritative;
|
||||
- Activity, progress, and staged mutation surfaces in Studio must reflect packer-native lifecycle, not replace it.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It prevents split-brain semantics between packer and Studio.
|
||||
- It keeps packer behavior testable outside JavaFX.
|
||||
- It allows Studio UI iteration without moving domain rules into the UI layer.
|
||||
- It gives concurrency and observability one owner, which is necessary for deterministic mutation and build behavior.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not define:
|
||||
|
||||
- the final internal threading primitives or executor topology of `prometeu-packer`;
|
||||
- a watch daemon or continuous background worker model;
|
||||
- remote/shared cache coordination;
|
||||
- cross-project scheduling policy beyond allowing separate projects to coordinate independently;
|
||||
- final event transport beyond the local adapter/event sink model currently planned.
|
||||
|
||||
## Implications
|
||||
|
||||
- read adapters belong in the packer integration track, not in Studio-local filesystem services;
|
||||
- mutation preview/apply semantics belong in packer services and only map into Studio staged UI models;
|
||||
- Studio Activity and progress integration must preserve packer causality metadata, even if the UI renders a simplified form;
|
||||
- tests must verify both same-project write serialization and event ordering through the Studio adapter path.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- [`../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md)
|
||||
- [`../pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](../pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md)
|
||||
- [`../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md`](../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md)
|
||||
|
||||
Cross-domain references:
|
||||
|
||||
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md`](../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
|
||||
Implementation surfaces:
|
||||
|
||||
- future `prometeu-packer` service contracts and event sink abstractions
|
||||
- Studio packer read/write/event adapters
|
||||
- Studio Activity/progress mapping code
|
||||
|
||||
## Validation Notes
|
||||
|
||||
The decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- the same packer operation can be replayed and observed without Studio inventing hidden state;
|
||||
- conflicting writes on one project cannot commit concurrently;
|
||||
- Activity/progress in Studio can be driven from packer-native events alone;
|
||||
- Studio summaries are either direct packer outputs or remapped packer outputs, never independent semantic recomputation.
|
||||
@ -1,175 +0,0 @@
|
||||
# Filesystem-First Operational Runtime and Reconcile Boundary Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-15
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Context
|
||||
|
||||
The current packer model already has the right core separation:
|
||||
|
||||
- `assets/.prometeu/index.json` is the authoritative registry/catalog for managed assets;
|
||||
- each asset root is anchored by `asset.json`;
|
||||
- `asset.json` is the authoring-side declaration of how that asset is packed;
|
||||
- Studio is meant to consume packer-owned operational semantics instead of recreating them locally.
|
||||
|
||||
What is still missing is a clear architectural decision for how the packer should behave operationally at runtime.
|
||||
|
||||
The repository now needs an answer to these questions:
|
||||
|
||||
1. should the packer remain a collection of direct filesystem services, recomputing state per request;
|
||||
2. should the packer become a pure database-style system that displaces the open filesystem workflow;
|
||||
3. or should it become a filesystem-first operational runtime that maintains an in-memory snapshot while preserving the workspace as the durable authoring surface.
|
||||
|
||||
The wrong answer here would create product friction.
|
||||
|
||||
If the packer behaves like a pure database, it will fight the real creative workflow where developers:
|
||||
|
||||
- edit files with their preferred tools;
|
||||
- move directories manually when needed;
|
||||
- inspect and version workspace files directly;
|
||||
- expect the Studio to help organize work, not imprison it.
|
||||
|
||||
At the same time, if the packer stays purely filesystem-per-call, it will remain too expensive, too incoherent under concurrent use, and too weak as the operational source of truth for Studio.
|
||||
|
||||
## Decision
|
||||
|
||||
The following direction is adopted:
|
||||
|
||||
1. `prometeu-packer` remains `filesystem-first`.
|
||||
2. The packer becomes a `project-scoped operational runtime`, not a pure database.
|
||||
3. The packer maintains an in-memory project snapshot for live operational reads and write coordination.
|
||||
4. The durable authoring workspace on disk remains the final persisted source of truth.
|
||||
5. The packer owns request/response read and write APIs over that runtime snapshot.
|
||||
6. Writes execute through a packer-owned project write lane and become durably visible only after commit succeeds.
|
||||
7. The packer will support background divergence detection between runtime snapshot and filesystem state.
|
||||
8. Divergence detection must surface reconcile state explicitly; it must not silently invent or hide semantic repairs.
|
||||
9. Studio remains a frontend consumer of packer responses, commands, and events.
|
||||
10. When embedded inside Studio, the packer runtime is bootstrapped with a typed event bus reference supplied by the Studio bootstrap container.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Filesystem-First Authority
|
||||
|
||||
- the asset workspace under `assets/` remains the authoring environment;
|
||||
- `asset.json` remains the asset-local declaration contract;
|
||||
- `assets/.prometeu/index.json` remains the authoritative registry/catalog for managed assets;
|
||||
- the packer runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring format.
|
||||
|
||||
### 2. Identity and Declaration Split
|
||||
|
||||
- `asset_id`, `included_in_build`, and registry-managed location tracking remain registry/catalog concerns;
|
||||
- `asset.json` remains primarily a declaration of the asset contract and packing inputs/outputs;
|
||||
- `asset.json` may carry the asset-local identity anchor needed for reconcile, specifically `asset_uuid`;
|
||||
- `asset.json` must not become a dumping ground for transient UI state, cache state, or catalog-derived bookkeeping that belongs in `index.json` or other packer-owned control files.
|
||||
|
||||
### 3. Snapshot-Backed Read Semantics
|
||||
|
||||
- normal read APIs should serve from a coherent in-memory project snapshot;
|
||||
- the packer must not require a full workspace recomputation for every normal read call once the runtime is active;
|
||||
- concurrent reads may proceed when they observe a coherent snapshot generation;
|
||||
- reads must not expose torn intermediate write state as committed truth.
|
||||
|
||||
### 4. Packer-Owned Write Execution
|
||||
|
||||
- write operations on one project are coordinated by the packer, not by caller timing;
|
||||
- the baseline policy remains a single-writer semantic lane per project;
|
||||
- write intent may compute previews before final commit when safe;
|
||||
- final apply/commit remains serialized per project;
|
||||
- successful durable commit defines post-write visibility.
|
||||
|
||||
### 5. Durable Commit Boundary
|
||||
|
||||
- the packer runtime may stage write changes in memory before disk commit;
|
||||
- partially applied intermediate state must not be presented as durably committed truth;
|
||||
- commit failure must leave the project in an explicitly diagnosable condition;
|
||||
- recovery and reconcile rules must be designed as packer behavior, not delegated to Studio guesswork.
|
||||
|
||||
### 6. Divergence Detection and Reconcile
|
||||
|
||||
- a future packer-owned background observation path may detect divergence between runtime snapshot and filesystem state;
|
||||
- this path exists to keep the runtime honest with respect to manual or external edits;
|
||||
- divergence must result in explicit runtime state such as stale, diverged, reconciling, or failed;
|
||||
- the packer must not silently rewrite user content just because divergence was observed;
|
||||
- reconcile is an explicit packer-owned behavior and must preserve causality in events and responses.
|
||||
|
||||
### 7. Studio Consumer Boundary
|
||||
|
||||
- Studio consumes packer read responses, write outcomes, and packer-native lifecycle events;
|
||||
- Studio may render stale/diverged/reconciling states, but must not invent packer-side reconcile semantics;
|
||||
- Studio must not become the owner of filesystem-vs-snapshot conflict resolution;
|
||||
- the Studio integration contract should remain command-oriented and event-driven.
|
||||
|
||||
### 8. Embedded Event Bus Bootstrap
|
||||
|
||||
- when the packer is embedded inside Studio, it must receive a typed event bus reference during bootstrap instead of creating an unrelated local event system;
|
||||
- that reference is used for packer event publication and any packer-side subscription/unsubscription behavior needed by the embedded runtime;
|
||||
- in Studio, the owner of that typed event bus reference is the application container;
|
||||
- the Studio `Container` must be initialized as part of Studio boot before packer-backed workspaces or adapters start consuming packer services.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It preserves the developer's open creative workflow around normal files and directories.
|
||||
- It keeps the packer useful as an organizing and coordinating system instead of turning it into an opaque silo.
|
||||
- It allows fast and coherent reads for Studio and tooling.
|
||||
- It gives write coordination, commit visibility, and operational causality one owner.
|
||||
- It creates a realistic path toward future background divergence detection without pretending that the filesystem stopped mattering.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not define:
|
||||
|
||||
- the final class/module names of the packer runtime implementation;
|
||||
- the final executor/thread primitive used internally;
|
||||
- the exact event vocabulary for all future reconcile states;
|
||||
- the final automatic-vs-manual reconcile policy for each drift scenario;
|
||||
- a watch-service or daemon transport implementation;
|
||||
- remote or multi-process synchronization;
|
||||
- a pure database persistence model.
|
||||
|
||||
## Implications
|
||||
|
||||
- the packer runtime track must preserve `index.json` plus `asset.json` as the durable workspace artifacts;
|
||||
- `asset.json` should evolve carefully to support local identity anchoring without absorbing catalog-only fields;
|
||||
- the runtime snapshot should be described as an operational cache/projection with authority for live service behavior, not as a new authoring truth;
|
||||
- mutation, doctor, build, and read services should converge on the same runtime state model;
|
||||
- future drift detection work must be designed together with diagnostics, refresh, and reconcile surfaces in Studio.
|
||||
- embedded Studio wiring must preserve one container-owned typed event bus reference instead of fragmented packer-local bus ownership.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- [`../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
|
||||
|
||||
Cross-domain references:
|
||||
|
||||
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
Implementation surfaces:
|
||||
|
||||
- future packer project-runtime/bootstrap code
|
||||
- snapshot-backed read services
|
||||
- project write-lane and durable commit pipeline
|
||||
- drift detection and reconcile state reporting
|
||||
- Studio packer adapters for stale/diverged/reconciling operational states
|
||||
- Studio bootstrap/container wiring for the shared typed event bus reference
|
||||
|
||||
## Validation Notes
|
||||
|
||||
This decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- developers may continue to inspect and edit asset workspace files directly;
|
||||
- packer reads are coherent without requiring full recomputation on each normal request;
|
||||
- same-project writes remain serialized by the packer;
|
||||
- Studio does not observe torn committed truth during write activity;
|
||||
- divergence between runtime snapshot and filesystem state can be detected and surfaced explicitly;
|
||||
- Studio remains a consumer of packer-owned reconcile and lifecycle semantics rather than inventing them.
|
||||
@ -1,146 +0,0 @@
|
||||
# Metadata Convergence to AssetEntry.metadata Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-17
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/vm-arch`, runtime asset consumers
|
||||
|
||||
## Context
|
||||
|
||||
The packer asset contract currently has multiple metadata-producing sources with different responsibilities:
|
||||
|
||||
- asset-level runtime contract metadata (authoring declaration);
|
||||
- codec-related metadata (codec configuration/effective codec parameters);
|
||||
- pipeline-derived metadata generated during build materialization (for example, indexed ranges for packed samples).
|
||||
|
||||
At runtime, consumers read one metadata sink from the asset table: `AssetEntry.metadata`.
|
||||
|
||||
Without an explicit decision, the system risks inconsistent behavior and documentation drift:
|
||||
|
||||
- metadata spread across sources without deterministic merge semantics;
|
||||
- ambiguity between storage-layout fields (`AssetEntry.offset`/`AssetEntry.size`) and pipeline-internal indexing data (`offset`/`length` per sample);
|
||||
- Studio, packer, and runtime docs diverging on where runtime consumers should read final values.
|
||||
|
||||
## Decision
|
||||
|
||||
The following direction is adopted:
|
||||
|
||||
1. All runtime-consumable metadata must converge to a single sink: `AssetEntry.metadata`.
|
||||
2. Source segmentation in `asset.json` is allowed for authoring clarity, but build materialization must normalize these sources into that single sink.
|
||||
3. Metadata normalization must be deterministic and testable.
|
||||
4. `AssetEntry.offset` and `AssetEntry.size` remain payload slicing fields and are not reinterpreted as pipeline-internal indexing metadata.
|
||||
5. Pipeline indexing metadata (for example, audio per-`sample_id` ranges) must live inside `AssetEntry.metadata` under explicit keys.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Source Segmentation vs Runtime Sink
|
||||
|
||||
- authoring sources may remain segmented (asset metadata, codec metadata, pipeline metadata);
|
||||
- runtime consumers must read effective values from `AssetEntry.metadata`;
|
||||
- packer build output is responsible for normalization.
|
||||
|
||||
### 2. Deterministic Convergence
|
||||
|
||||
- normalization must produce the same `AssetEntry.metadata` for the same effective declaration and build inputs;
|
||||
- metadata key collisions between independent sources must be rejected with a build-time error unless explicitly specified by family/format contract;
|
||||
- normalization order and collision policy must be documented by packer specs.
|
||||
|
||||
### 3. Audio Indexing Semantics
|
||||
|
||||
For multi-sample audio banks, sample indexing metadata belongs to `AssetEntry.metadata`, keyed by `sample_id`.
|
||||
|
||||
Illustrative shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"sample_rate": 22050,
|
||||
"channels": 1,
|
||||
"samples": {
|
||||
"1": { "offset": 0, "length": 100 }
|
||||
},
|
||||
"codec": {
|
||||
"parity": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This decision accepts either nested codec metadata (for example `metadata.codec.*`) or a flat equivalent only when the family/format spec declares that shape explicitly.
|
||||
|
||||
### 4. Offset Ambiguity Guardrail
|
||||
|
||||
- `AssetEntry.offset`/`AssetEntry.size` describe where one packed asset payload is stored in `assets.pa`;
|
||||
- `metadata.samples[*].offset`/`metadata.samples[*].length` describe internal layout/indexing inside that asset's runtime payload contract;
|
||||
- documentation and tests must keep these meanings separate.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It keeps runtime consumption simple: one metadata sink.
|
||||
- It preserves authoring ergonomics: source metadata can stay segmented by concern.
|
||||
- It avoids semantic duplication between packer and runtime consumers.
|
||||
- It creates a clear path for bank-like assets (tiles/audio) that require indexed internal metadata.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not define:
|
||||
|
||||
- the final complete metadata schema for every asset family;
|
||||
- the final canonical codec metadata shape (`nested` vs `flat`) for all formats;
|
||||
- multi-sample audio runtime loading implementation details;
|
||||
- exact binary container/header layout for audio banks.
|
||||
|
||||
## Implications
|
||||
|
||||
- packer specs must define normalization semantics and collision policy;
|
||||
- packer build/materialization must emit normalized metadata into `AssetEntry.metadata`;
|
||||
- runtime-facing docs must state that effective metadata is read from `AssetEntry.metadata`;
|
||||
- tests must cover convergence correctness and ambiguity boundaries for offset semantics.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../../vm-arch/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- next packer PR/plan that introduces metadata normalization and multi-source merge validation
|
||||
|
||||
Code:
|
||||
|
||||
- packer asset declaration/materialization pipeline
|
||||
- asset table emission path (`AssetEntry.metadata` payload)
|
||||
|
||||
Tests:
|
||||
|
||||
- normalization unit tests (source merge determinism)
|
||||
- collision/ambiguity tests for offset semantics
|
||||
- regression tests for runtime-readable metadata shape
|
||||
|
||||
Docs:
|
||||
|
||||
- packer specs and learn artifacts covering metadata source-to-sink flow
|
||||
- runtime asset-management documentation referencing `AssetEntry.metadata` as sink
|
||||
|
||||
## References
|
||||
|
||||
Related specs:
|
||||
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
|
||||
Related agendas:
|
||||
|
||||
- no formal agenda artifact yet for this specific topic; this decision consolidates current packer/runtime alignment discussion.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
This decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- runtime consumers can read final effective metadata exclusively from `AssetEntry.metadata`;
|
||||
- segmented metadata sources in authoring inputs converge deterministically during packing;
|
||||
- offset semantics remain unambiguous between asset-table payload slicing and pipeline-internal indexing;
|
||||
- documentation across packer and runtime-facing domains is consistent about this source-to-sink contract.
|
||||
@ -1,218 +0,0 @@
|
||||
# Pack Wizard Pack Execution Semantics Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-20
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Context
|
||||
|
||||
The Studio-side `Pack Wizard` flow is already closed as a shell over packer-owned operations.
|
||||
|
||||
On the packer side, the repository also already closed the first-wave `summary` and `validation` contracts.
|
||||
|
||||
What remained open was the execution contract for the actual pack operation:
|
||||
|
||||
- how `packWorkspace(...)` should behave when Studio enters `Packing` and `Result`;
|
||||
- how the packer should avoid filesystem drift while packing;
|
||||
- how final artifact visibility should be protected during emission;
|
||||
- and how the operation should report success, blocking failure, and execution failure without pushing semantic reconstruction into Studio.
|
||||
|
||||
The agenda that closed this discussion is:
|
||||
|
||||
- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
|
||||
|
||||
Relevant upstream references are:
|
||||
|
||||
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
|
||||
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
|
||||
## Decision
|
||||
|
||||
The first-wave packer execution contract for the `Pack Wizard` adopts the following direction:
|
||||
|
||||
1. `packWorkspace(...)` is one packer-owned public operation.
|
||||
2. It executes through the project-scoped serialized write lane.
|
||||
3. It must rerun a packer-owned gate check before artifact emission begins.
|
||||
4. It must pack from one frozen execution snapshot rather than from live filesystem rereads.
|
||||
5. It must stage emitted outputs before promotion to final `build/` locations.
|
||||
6. It publishes final build artifacts to `build/` only after a coherent success point is reached.
|
||||
7. It remains the only first-wave operation that emits build artifacts for the Studio `Pack Wizard`.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Execution Boundary
|
||||
|
||||
- `packWorkspace(...)` evaluates the active pack set as `registered + included in build`;
|
||||
- it runs under the same packer-owned project write serialization model already adopted for same-project writes and build operations;
|
||||
- it must not trust Studio call ordering as if that were a correctness guarantee;
|
||||
- a failing pack gate returns a terminal result without publishing final build artifacts.
|
||||
|
||||
### 2. Frozen Execution Snapshot
|
||||
|
||||
- pack execution must not reread live workspace files once execution materialization begins;
|
||||
- the packer must create a frozen pack-execution snapshot before payload materialization starts;
|
||||
- that frozen snapshot is derived from the current runtime snapshot and packer-owned walk/materialization path;
|
||||
- file content bytes are required only for build-relevant inputs:
|
||||
- registered assets included in build;
|
||||
- artifact files that actually participate in the current build output;
|
||||
- non-build assets and non-selected artifact files do not need in-memory content in the pack-execution snapshot.
|
||||
|
||||
### 3. Runtime Walk Projection Shape
|
||||
|
||||
- the existing runtime walk projection model remains the baseline;
|
||||
- `PackerRuntimeWalkFile` gains optional content bytes instead of introducing a second snapshot model in the first wave;
|
||||
- optional content bytes remain absent in normal runtime-backed projection and become present only in packing-focused projection.
|
||||
|
||||
### 4. Materialization Policy Shape
|
||||
|
||||
The adopted first-wave shape is:
|
||||
|
||||
```java
|
||||
public record PackerRuntimeMaterializationConfig(
|
||||
PackerWalkMode mode,
|
||||
Predicate<PackerProbeResult> projectionFilter) {
|
||||
|
||||
public static PackerRuntimeMaterializationConfig runtimeDefault() {
|
||||
return new PackerRuntimeMaterializationConfig(PackerWalkMode.RUNTIME, probe -> true);
|
||||
}
|
||||
|
||||
public static PackerRuntimeMaterializationConfig packingBuild() {
|
||||
return new PackerRuntimeMaterializationConfig(
|
||||
PackerWalkMode.PACKING,
|
||||
PackerProbePolicies::isIncludedInCurrentBuild);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With this contract:
|
||||
|
||||
- `PackerWalkMode.RUNTIME` suppresses optional content bytes during export to runtime walk projection;
|
||||
- `PackerWalkMode.PACKING` injects optional content bytes during export to runtime walk projection;
|
||||
- `projectionFilter` decides which discovered probe results survive into `PackerRuntimeWalkFile`;
|
||||
- the first-wave packing filter keeps only current-build probe results.
|
||||
|
||||
### 5. Walker Boundary
|
||||
|
||||
- family walkers remain family-oriented discovery mechanisms;
|
||||
- they may continue to produce full file probes with bytes available during probe processing;
|
||||
- the runtime-versus-packing variation happens during export/materialization into runtime walk projection;
|
||||
- packing-specific selection is one additional projection/materialization policy layer over the discovered probe results;
|
||||
- first-wave pack execution must not fork the repository into one discovery model for runtime and another discovery model for packing.
|
||||
|
||||
### 6. Staging and Promotion Boundary
|
||||
|
||||
- pack execution stages outputs under `build/.staging/<operation-id>/`;
|
||||
- `<operation-id>` is one random 20-character alphanumeric identifier;
|
||||
- if a staging directory collision occurs for that identifier, the packer may overwrite that staging directory in the first wave;
|
||||
- staged outputs are non-authoritative until promotion;
|
||||
- promotion into final `build/` locations happens only after the operation reaches a coherent success point;
|
||||
- if emission fails before promotion, final `build/` outputs must remain unchanged from the caller's point of view.
|
||||
|
||||
### 7. Build Publication Boundary
|
||||
|
||||
- the canonical runtime-facing output is `build/assets.pa`;
|
||||
- the baseline companion outputs are:
|
||||
- `build/asset_table.json`
|
||||
- `build/preload.json`
|
||||
- `build/asset_table_metadata.json`
|
||||
- `packWorkspace(...)` stops at build artifact publication;
|
||||
- shipper behavior remains outside this operation and is mentioned only as a future consumer boundary.
|
||||
|
||||
### 8. Result and Failure Semantics
|
||||
|
||||
The final pack result must distinguish at least:
|
||||
|
||||
1. validation gate failure before emission;
|
||||
2. execution or materialization failure during pack generation;
|
||||
3. persistence or promotion failure while making outputs final.
|
||||
|
||||
The first-wave result summary must expose at least:
|
||||
|
||||
- final status;
|
||||
- whether execution actually began or stopped at gate failure;
|
||||
- canonical build-relative reference to `assets.pa`;
|
||||
- build-relative companion artifact references when emitted;
|
||||
- total packed asset count;
|
||||
- elapsed time in milliseconds.
|
||||
|
||||
### 9. Minimum Structural Conformance
|
||||
|
||||
The first-wave pack execution is not successful unless the emitted outputs satisfy the already adopted baseline structural guarantees:
|
||||
|
||||
- `asset_table` ordering is deterministic by increasing `asset_id`;
|
||||
- header serialization is canonical;
|
||||
- offsets are relative to `payload_offset`;
|
||||
- preload entries are resolved by `asset_id`;
|
||||
- invalid preload references or preload slot clashes fail the operation rather than being deferred to host guesswork.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It preserves packer ownership of build semantics while keeping Studio as an honest shell.
|
||||
- It prevents filesystem drift during execution without turning the general runtime snapshot into a wasteful full-memory mirror.
|
||||
- It aligns build visibility with the same commit-oriented operational model already adopted elsewhere in the packer runtime.
|
||||
- It keeps the first-wave implementation on known terrain by reusing current walker/materialization structure instead of inventing a second discovery stack.
|
||||
- It gives the Studio enough structured outcome information to render `Packing` and `Result` without semantic reconstruction.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the format-specific payload materialization rules for each asset output format;
|
||||
- the canonical payload contract for `tile bank`, `sound bank`, or other family-specific outputs;
|
||||
- the final event kind vocabulary for pack execution progress beyond requiring causality-preserving observable lifecycle;
|
||||
- cancellation semantics;
|
||||
- future incremental or remote build behavior;
|
||||
- shipper packaging rules, cartridge manifest generation, or final packaged cartridge layout.
|
||||
|
||||
## Implications
|
||||
|
||||
- `packWorkspace(...)` can no longer be implemented as a direct live-filesystem read/write shortcut;
|
||||
- runtime walk projection and materialization code must gain explicit packing-aware export policy;
|
||||
- `PackerRuntimeWalkFile` must support optional content bytes;
|
||||
- pack execution implementation must include frozen-input creation, staging, promotion, and structured terminal outcomes;
|
||||
- format-specific packing discussions must now happen as follow-up decisions rather than being guessed inside the generic execution path.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- [`../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
||||
- [`../pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](../pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
|
||||
- future packer PR for pack execution, staging, and result semantics
|
||||
|
||||
Cross-domain references:
|
||||
|
||||
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
- [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
|
||||
|
||||
Follow-up agenda references:
|
||||
|
||||
- [`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md)
|
||||
|
||||
Implementation surfaces:
|
||||
|
||||
- `prometeu-packer-api` pack execution result contract
|
||||
- `prometeu-packer-v1` runtime materialization/export policy
|
||||
- `prometeu-packer-v1` frozen execution snapshot creation
|
||||
- `prometeu-packer-v1` staging and promote pipeline
|
||||
- Studio `Pack Wizard` packing/result bindings
|
||||
|
||||
## Validation Notes
|
||||
|
||||
This decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- `packWorkspace(...)` does not depend on live filesystem rereads after frozen execution materialization begins;
|
||||
- only build-relevant selected inputs carry frozen content bytes into the packing path;
|
||||
- normal runtime-backed reads do not retain optional content bytes by default;
|
||||
- failed execution before promotion does not leave partial final `build/` artifacts presented as success;
|
||||
- successful pack publication produces `build/assets.pa` and the expected companion outputs coherently;
|
||||
- Studio can distinguish blocked, failed, and successful pack outcomes from packer-owned results alone.
|
||||
@ -1,174 +0,0 @@
|
||||
# Pack Wizard Summary and Validation Contracts Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-20
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Context
|
||||
|
||||
The Studio `Pack Wizard` flow is now closed on the host side as a shell over packer-owned operations.
|
||||
|
||||
That decision already fixed the outer boundary:
|
||||
|
||||
- Studio is the shell;
|
||||
- packer owns summary, validation, pack execution, progress, and result semantics;
|
||||
- the wizard flow is phase-based;
|
||||
- the active pack set is the current `registered + included in build` set.
|
||||
|
||||
On the packer side, the first remaining need is to close the public contract for `summary` and `validation` before the repository moves deeper into pack execution semantics.
|
||||
|
||||
This decision consolidates the `summary` and `validation` part of the packer-side discussion from:
|
||||
|
||||
- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
|
||||
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
|
||||
The main question is not whether Studio should have these phases.
|
||||
That is already settled.
|
||||
The question is what the packer must expose as the authoritative public contract for those phases.
|
||||
|
||||
## Decision
|
||||
|
||||
The packer public contract for the `Pack Wizard` first wave adopts the following direction:
|
||||
|
||||
1. `summary` and `validation` are distinct packer operations;
|
||||
2. both operations are read-only and non-mutating;
|
||||
3. both operations evaluate the same pack set:
|
||||
`registered + included in build`;
|
||||
4. both operations are packer-owned and snapshot-backed;
|
||||
5. Studio consumes these packer responses and must not reconstruct equivalent semantics locally.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Summary Boundary
|
||||
|
||||
- `summary` is a fast snapshot-backed preflight view;
|
||||
- `summary` must return from packer-owned snapshot state, not from a deep recomputation pass;
|
||||
- `summary` is not a build preview and must not imply that artifacts were emitted;
|
||||
- `summary` must not anticipate companion artifacts or emitted artifact details in the first wave;
|
||||
- `summary` must not include unregistered assets or excluded assets as explicit summary items.
|
||||
|
||||
### 2. Summary Shape
|
||||
|
||||
The first-wave `summary` contract contains:
|
||||
|
||||
1. one aggregate count for the active pack set;
|
||||
2. one per-asset list for the active pack set.
|
||||
|
||||
The aggregate is intentionally minimal in the first wave:
|
||||
|
||||
- total included asset count is sufficient.
|
||||
|
||||
Each per-asset summary entry must expose:
|
||||
|
||||
- `assetId`
|
||||
- `assetName`
|
||||
- `assetFamily`
|
||||
- `minArtifactCount`
|
||||
- `maxArtifactCount`
|
||||
- `lastModified`
|
||||
|
||||
`lastModified` is required in the public contract even if early implementations temporarily expose `0` until the real value is fully available per asset.
|
||||
|
||||
The per-asset summary list is the intended payload for Studio-side graphical occupancy presentation.
|
||||
The aggregate remains deliberately small.
|
||||
|
||||
### 3. Validation Boundary
|
||||
|
||||
- `validation` evaluates the same active pack set as `summary`;
|
||||
- `validation` is read-only and non-mutating;
|
||||
- `validation` is snapshot-backed;
|
||||
- `validation` may internally reuse deep-inspection or reconcile-grade logic where needed;
|
||||
- a future Studio flow may add an explicit deep-sync step before validation, but validation itself still evaluates the packer snapshot boundary.
|
||||
|
||||
### 4. Validation Failure Rule
|
||||
|
||||
Only diagnostics marked `blocking` fail validation in the first wave.
|
||||
|
||||
The rule is:
|
||||
|
||||
- if no blocking diagnostics are returned for the active pack set, validation is green;
|
||||
- if any blocking diagnostics are returned for the active pack set, validation is red and packing must not begin.
|
||||
|
||||
Warnings and non-blocking diagnostics are not part of the first-wave validation gate contract.
|
||||
|
||||
### 5. Validation Shape
|
||||
|
||||
The primary validation payload is the per-asset diagnostics list.
|
||||
|
||||
Aggregate validation data may still exist, but it is secondary.
|
||||
The Studio may derive aggregate visual summaries from the per-asset list if useful.
|
||||
|
||||
Each per-asset validation entry must expose:
|
||||
|
||||
- `assetId`
|
||||
- `assetName`
|
||||
- `assetPath`
|
||||
- `lastModified`
|
||||
- `diagnostics`
|
||||
|
||||
In the first wave, `diagnostics` in this contract means blocking diagnostics only.
|
||||
|
||||
Ordering is not a packer responsibility in the first-wave validation payload.
|
||||
The Studio may sort the returned list as needed for presentation.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It keeps `summary` and `validation` aligned with the existing request/result API style instead of inventing a special build-session protocol too early.
|
||||
- It keeps ownership where it belongs: the packer remains the source of truth for pack-set semantics and validation outcomes.
|
||||
- It gives Studio enough structured data to render the preflight and validation phases without recreating packer meaning.
|
||||
- It keeps the first-wave contract intentionally narrow so the repository can close `summary` and `validation` without prematurely locking the heavier `pack execution` semantics.
|
||||
- It gives the Studio enough per-asset detail to show useful occupancy and blocker views while keeping ordering and higher-level UI grouping on the host side.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the final `pack execution` request/result contract;
|
||||
- emitted artifact reporting rules beyond what is already upstream in packer artifact specs;
|
||||
- the final event vocabulary for pack progress;
|
||||
- whether future validation payloads should include non-blocking diagnostics;
|
||||
- the final source for real `lastModified` values in every asset case;
|
||||
- runtime-ingestion and cartridge-facing conformance gates for actual artifact emission.
|
||||
|
||||
## Implications
|
||||
|
||||
- the current public API work for pack summary must expand beyond aggregate-only shape;
|
||||
- the current public API work for validation must expand beyond generic aggregate-first DTOs;
|
||||
- Studio `Pack Wizard` binding should evolve toward the per-asset summary and per-asset validation payloads defined here;
|
||||
- `summary` and `validation` can now be implemented independently of the heavier pack execution discussion;
|
||||
- the next packer discussion wave should focus primarily on execution semantics, artifact emission guarantees, and runtime/cartridge ingestion conformance.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- [`../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
||||
|
||||
Cross-domain references:
|
||||
|
||||
- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
- [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
|
||||
|
||||
Implementation surfaces:
|
||||
|
||||
- `prometeu-packer-api` summary and validation request/result DTOs
|
||||
- snapshot-backed pack summary query logic
|
||||
- snapshot-backed pack validation logic
|
||||
- Studio pack wizard summary and validation bindings
|
||||
|
||||
## Validation Notes
|
||||
|
||||
This decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- `summary` returns quickly from packer-owned snapshot state;
|
||||
- Studio does not reconstruct pack summary from navigator rows or local UI state;
|
||||
- `summary` returns only active pack-set items, not excluded or unregistered items;
|
||||
- `validation` returns blocking-diagnostic information per asset for the same active pack set;
|
||||
- a returned validation payload with any blocking diagnostics stops the wizard before pack execution;
|
||||
- the Studio may reorder the returned lists without changing packer semantics.
|
||||
@ -1,17 +1,12 @@
|
||||
# Packer Decisions
|
||||
|
||||
This directory contains packer decision records.
|
||||
This directory contains packer decision records that still need propagation.
|
||||
|
||||
Retained packer decision records:
|
||||
Current retained set:
|
||||
|
||||
- [`Concurrency, Observability, and Studio Adapter Boundary Decision.md`](./Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
|
||||
- [`Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](./Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)
|
||||
- [`Metadata Convergence to AssetEntry.metadata Decision.md`](./Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
|
||||
- [`Pack Wizard Summary and Validation Contracts Decision.md`](./Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
|
||||
- [`Pack Wizard Pack Execution Semantics Decision.md`](./Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- [`Tile Bank Packing Materialization Decision.md`](./Tile%20Bank%20Packing%20Materialization%20Decision.md)
|
||||
- none
|
||||
|
||||
The first packer decision wave was already consolidated into:
|
||||
The current packer decision wave has already been consolidated into:
|
||||
|
||||
- normative specifications under [`../specs/`](../specs/)
|
||||
- didactic material under [`../learn/`](../learn/)
|
||||
|
||||
@ -1,211 +0,0 @@
|
||||
# Tile Bank Packing Materialization Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-20
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `../runtime`, `docs/studio`
|
||||
|
||||
## Context
|
||||
|
||||
The packer execution contract for `packWorkspace(...)` is already closed.
|
||||
|
||||
What remained open for `tile bank` was the format-specific producer contract:
|
||||
|
||||
- which selected files become part of the packed asset;
|
||||
- how those files become the canonical `TILES/indexed_v1` payload;
|
||||
- how `AssetEntry` fields are derived for runtime consumption;
|
||||
- how bank palettes are declared and normalized;
|
||||
- which diagnostics block the build for this format.
|
||||
|
||||
The agenda that closed this discussion is:
|
||||
|
||||
- [`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md)
|
||||
|
||||
Relevant upstream references are:
|
||||
|
||||
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md`](../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md)
|
||||
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
|
||||
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
- [`../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md`](../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md)
|
||||
|
||||
## Decision
|
||||
|
||||
The first-wave packer materialization contract for `tile bank` adopts the following direction:
|
||||
|
||||
1. `TILES/indexed_v1` emits one canonical payload per asset.
|
||||
2. `1 artifact = 1 tile` in the first wave.
|
||||
3. Artifacts are ordered by normalized `artifacts[*].index`.
|
||||
4. Tile placement is row-major in one fixed `256 x 256` sheet.
|
||||
5. `tile_id` is the linear row-major slot and therefore matches the normalized artifact index.
|
||||
6. Tile pixels are serialized as packed `u4` indices.
|
||||
7. Bank palettes are serialized as `RGB565` `u16` values.
|
||||
8. Palette declarations use explicit semantic identity through `{ index, palette }`.
|
||||
9. `AssetEntry.metadata` keeps required runtime fields readable at the root while preserving segmented codec and pipeline subtrees.
|
||||
10. Format-structural diagnostics are raised in the walker/materialization path and therefore participate in validation before pack execution reruns the gate.
|
||||
|
||||
## Adopted Constraints
|
||||
|
||||
### 1. Canonical Payload Shape
|
||||
|
||||
- the payload is produced from build-selected artifacts only;
|
||||
- the payload is the canonical bank sheet raster, not a concatenation of per-artifact binary fragments;
|
||||
- for `TILES/indexed_v1`, the serialized payload shape is:
|
||||
1. packed `u4` pixel indices for the full emitted sheet;
|
||||
2. one palette block of `64 * 16 * 2` bytes;
|
||||
- palettes are always materialized to `RGB565` during pack emission;
|
||||
- the producer-side payload contract is aligned to what the runtime loader already requires.
|
||||
|
||||
### 2. Artifact-to-Tile Contract
|
||||
|
||||
- `1 artifact = 1 tile` in v1;
|
||||
- artifacts are normalized by `artifacts[*].index`;
|
||||
- `tile_id = artifacts[*].index` after normalization;
|
||||
- the canonical emitted sheet is always `256 x 256`;
|
||||
- placement is row-major within that fixed sheet.
|
||||
|
||||
Resulting tile capacities:
|
||||
|
||||
- `tile_size = 8` -> `32 x 32 = 1024` tiles
|
||||
- `tile_size = 16` -> `16 x 16 = 256` tiles
|
||||
- `tile_size = 32` -> `8 x 8 = 64` tiles
|
||||
|
||||
### 3. Runtime Entry Contract
|
||||
|
||||
Each emitted `tile bank` runtime entry must populate:
|
||||
|
||||
- `asset_id`
|
||||
- `asset_name`
|
||||
- `bank_type = TILES`
|
||||
- `offset`
|
||||
- `size`
|
||||
- `decoded_size`
|
||||
- `codec = NONE`
|
||||
- `metadata`
|
||||
|
||||
For v1:
|
||||
|
||||
- `size = ceil(width * height / 2) + 2048`
|
||||
- `decoded_size = (width * height) + 2048`
|
||||
- `width = 256`
|
||||
- `height = 256`
|
||||
- `palette_count = 64`
|
||||
|
||||
### 4. Palette Contract
|
||||
|
||||
- bank palettes are declared in `asset.json.output.pipeline.palettes`;
|
||||
- each palette declaration must use explicit shape `{ index, palette }`;
|
||||
- semantic ordering is ascending numeric `index`, never raw array position;
|
||||
- palette ids are the normalized declared `index` values;
|
||||
- any tile in the bank may be rendered with any palette in the bank;
|
||||
- palette choice is a runtime draw-time concern and is not embedded per tile in the packed payload.
|
||||
|
||||
### 5. Metadata Normalization Contract
|
||||
|
||||
`AssetEntry.metadata` keeps runtime-required fields readable while preserving authoring segmentation:
|
||||
|
||||
- `asset.json.output.metadata` -> `AssetEntry.metadata`
|
||||
- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
|
||||
- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
|
||||
|
||||
For tile-bank v1 this means:
|
||||
|
||||
- `tile_size`, `width`, `height`, and `palette_count` remain directly readable at the metadata root;
|
||||
- codec-specific data is nested under `metadata.codec`;
|
||||
- pipeline-derived data is nested under `metadata.pipeline`.
|
||||
|
||||
This packer decision intentionally aligns with the runtime-side follow-up agenda rather than flattening everything into one ambiguous map.
|
||||
|
||||
### 6. Diagnostics and Failure Semantics
|
||||
|
||||
The following conditions are blocking for tile-bank v1:
|
||||
|
||||
- duplicate `artifacts[*].index`
|
||||
- gaps in normalized `artifacts[*].index`
|
||||
- fixed-sheet capacity overflow
|
||||
- bank without declared palettes
|
||||
- palette declaration count above `64`
|
||||
- malformed palette declarations
|
||||
- missing or invalid required format metadata
|
||||
- any failure to normalize artifacts into one deterministic payload
|
||||
|
||||
The following condition is warning-only in the first wave:
|
||||
|
||||
- fragile tile indices, meaning tile indices that are not safely represented across the full declared bank palette set
|
||||
|
||||
### 7. Walker and Validation Boundary
|
||||
|
||||
- family walkers remain discovery-oriented;
|
||||
- tile-bank structural diagnostics must be produced in the walker/materialization path;
|
||||
- validation consumes those diagnostics naturally;
|
||||
- pack execution reruns the validation gate on a newly created frozen execution snapshot before materialization begins.
|
||||
|
||||
## Why This Direction Was Chosen
|
||||
|
||||
- It matches the runtime consumer contract instead of inventing a producer-local interpretation.
|
||||
- It keeps `tile bank` payload semantics explicit and deterministic.
|
||||
- It avoids embedding per-artifact or per-draw palette assignment into the packed bytes.
|
||||
- It preserves stable palette identity through explicit `index` declarations.
|
||||
- It keeps validation early without weakening the pack-time rerun gate.
|
||||
- It gives the runtime a metadata shape that is readable and still semantically segmented.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- future support for `1 artifact -> many tiles`;
|
||||
- non-`256 x 256` tile-bank targets;
|
||||
- alternative tile-bank codecs beyond `NONE`;
|
||||
- future palette compaction or palette-id remapping strategies;
|
||||
- the runtime-side final decision for general `AssetEntry.metadata` normalization helpers;
|
||||
- future sprite or tilemap semantic adjustments unrelated to packer-owned payload production.
|
||||
|
||||
## Implications
|
||||
|
||||
- tile-bank packing implementation must materialize a full sheet raster rather than artifact fragments;
|
||||
- tile-bank payload generation must pack `u4` indices explicitly in the packer;
|
||||
- palette declarations and palette overhauling flows must preserve explicit palette `index`;
|
||||
- runtime-entry metadata emission must preserve both root-required fields and segmented nested maps;
|
||||
- tile-bank validation logic belongs in the walker/materialization path and must be reused by pack execution gate reruns.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
Specs:
|
||||
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
|
||||
Plans:
|
||||
|
||||
- [`../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md`](../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md)
|
||||
- future packer PR for tile-bank payload materialization
|
||||
- future packer PR for tile-bank validation diagnostics
|
||||
|
||||
Cross-domain references:
|
||||
|
||||
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
|
||||
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
- [`../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md`](../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md)
|
||||
- [`../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md`](../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md)
|
||||
|
||||
Implementation surfaces:
|
||||
|
||||
- `prometeu-packer-v1` tile-bank payload materializer
|
||||
- `prometeu-packer-v1` tile-bank diagnostics in walker/materialization path
|
||||
- `prometeu-packer-v1` metadata convergence for `AssetEntry`
|
||||
- Studio tile-bank authoring and inspection surfaces that expose palettes or bank composition
|
||||
|
||||
## Validation Notes
|
||||
|
||||
This decision is correctly implemented only when all of the following are true:
|
||||
|
||||
- artifact normalization produces one deterministic row-major `256 x 256` bank sheet;
|
||||
- emitted tile ids match normalized artifact indices;
|
||||
- emitted pixel bytes are packed as `u4`;
|
||||
- emitted palette bytes are `RGB565` `u16`;
|
||||
- palette declarations are read and written by explicit `index`;
|
||||
- runtime-required metadata fields remain readable at the root;
|
||||
- codec and pipeline metadata survive under `metadata.codec` and `metadata.pipeline`;
|
||||
- structural blockers are visible during validation and are rerun by pack execution before emission.
|
||||
@ -52,4 +52,8 @@ Start here:
|
||||
|
||||
1. [`mental-model-packer.md`](./mental-model-packer.md)
|
||||
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
|
||||
3. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
|
||||
3. [`foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md)
|
||||
4. [`runtime-ownership-and-studio-boundary.md`](./runtime-ownership-and-studio-boundary.md)
|
||||
5. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
|
||||
6. [`pack-wizard-summary-validation-and-pack-execution.md`](./pack-wizard-summary-validation-and-pack-execution.md)
|
||||
7. [`tile-bank-packing-contract.md`](./tile-bank-packing-contract.md)
|
||||
|
||||
91
docs/packer/learn/foundations-workspace-runtime-and-build.md
Normal file
91
docs/packer/learn/foundations-workspace-runtime-and-build.md
Normal file
@ -0,0 +1,91 @@
|
||||
# Foundations: Workspace, Runtime, and Build
|
||||
|
||||
## Original Problem
|
||||
|
||||
The packer domain accumulated a long implementation wave covering workspace control, asset identity, scanning, mutations, diagnostics, deterministic planning, runtime snapshots, and cache reuse.
|
||||
|
||||
The historical PR chain was useful while the repository was converging, but it stopped being a good onboarding surface:
|
||||
|
||||
- too much knowledge was spread across execution slices;
|
||||
- too much reasoning depended on chronological reconstruction;
|
||||
- too little of that knowledge was available as one stable mental model.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable packer foundation is:
|
||||
|
||||
1. the workspace stays open and filesystem-first;
|
||||
2. `assets/.prometeu/index.json` owns managed identity and inclusion state;
|
||||
3. each asset root is anchored by `asset.json`;
|
||||
4. the packer runtime serves coherent snapshot-backed reads;
|
||||
5. writes are coordinated by the packer and become visible after durable commit;
|
||||
6. build outputs are derived deterministically from validated, packer-owned state.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Workspace and Identity
|
||||
|
||||
- `asset_id` is the stable managed identifier used for ordering, inclusion, and runtime-facing tables;
|
||||
- `asset_uuid` is the local identity anchor that helps reconcile the same logical asset across path movement;
|
||||
- `asset_name` is the logical human-facing identifier and is not a substitute for managed identity;
|
||||
- `asset.json` describes authoring intent, not registry-owned bookkeeping.
|
||||
|
||||
### 2. Read and Write Authority
|
||||
|
||||
- normal reads come from a coherent runtime snapshot rather than from ad hoc filesystem scans;
|
||||
- the filesystem still matters because it remains the durable authoring surface;
|
||||
- writes flow through packer-owned preview/apply semantics and one project-scoped serialized lane.
|
||||
|
||||
### 3. Deterministic Build Path
|
||||
|
||||
- only validated managed assets enter the build path;
|
||||
- asset ordering is deterministic by increasing `asset_id`;
|
||||
- runtime-facing artifacts are emitted from canonical packer-owned planning and materialization rules;
|
||||
- companion artifacts mirror build authority rather than define parallel truth.
|
||||
|
||||
### 4. Runtime Snapshot Evolution
|
||||
|
||||
The later runtime wave refined the first foundation:
|
||||
|
||||
- runtime state became explicitly project-scoped;
|
||||
- snapshot updates happen after successful write commit;
|
||||
- query services read from that runtime state;
|
||||
- cache layers exist to accelerate the same ownership model, not to bypass it.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why relocation does not create a new asset
|
||||
|
||||
If an asset root moves on disk, the packer should preserve the managed identity when the move is a relocation of the same logical asset.
|
||||
|
||||
That is why:
|
||||
|
||||
- the registry owns stable managed identity;
|
||||
- path is mutable operational state;
|
||||
- relocation updates root tracking without inventing a new `asset_id`.
|
||||
|
||||
### Example: Why filesystem order cannot define build order
|
||||
|
||||
Two equivalent workspaces may be traversed in different directory order.
|
||||
The build must still emit the same `asset_table` and payload layout.
|
||||
|
||||
That is why deterministic ordering is tied to managed identity, not traversal order.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating `asset_name` as if it were a stable runtime identifier.
|
||||
- Moving registry-owned fields into `asset.json`.
|
||||
- Recomputing semantic read models directly from Studio-side filesystem heuristics.
|
||||
- Letting build order depend on traversal order, cache insertion order, or UI ordering.
|
||||
- Treating cache state as semantic authority instead of as an optimization.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-packer.md`](./mental-model-packer.md)
|
||||
- [`./mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
|
||||
@ -24,10 +24,6 @@ The accepted direction is:
|
||||
4. collisions require explicit contract rules or must fail build;
|
||||
5. `AssetEntry.offset`/`AssetEntry.size` keep payload slicing semantics and do not replace internal pipeline indexing.
|
||||
|
||||
Decision reference:
|
||||
|
||||
- [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
|
||||
|
||||
## Final Model
|
||||
|
||||
Think in two layers:
|
||||
@ -77,6 +73,6 @@ In this model:
|
||||
|
||||
## References
|
||||
|
||||
- Decision: [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md)
|
||||
- Spec: [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- Related learn: [`./tile-bank-packing-contract.md`](./tile-bank-packing-contract.md)
|
||||
|
||||
@ -0,0 +1,118 @@
|
||||
# Pack Wizard: Summary, Validation, and Pack Execution
|
||||
|
||||
## Original Problem
|
||||
|
||||
The Studio-side wizard was already accepted as a shell over packer-owned operations, but the packer side still needed one coherent story for:
|
||||
|
||||
1. what `summary` means;
|
||||
2. what `validation` means;
|
||||
3. how `packWorkspace(...)` executes without trusting stale UI state or live filesystem rereads.
|
||||
|
||||
The historical agenda, decisions, and PRs solved this in slices.
|
||||
This document keeps the final model in one place.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The first-wave `Pack Wizard` contract is phase-based and fully packer-owned:
|
||||
|
||||
1. `summary` is a fast snapshot-backed preflight view;
|
||||
2. `validation` is a snapshot-backed gate over the same active pack set;
|
||||
3. `packWorkspace(...)` is the only artifact-emitting wizard operation;
|
||||
4. execution reruns the gate on a fresh frozen snapshot;
|
||||
5. outputs are staged before promotion into final `build/` locations.
|
||||
|
||||
The active pack set is always:
|
||||
|
||||
`registered + included in build`
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Summary
|
||||
|
||||
`summary` is not a build preview.
|
||||
It is a quick packer-owned view of the current active pack set.
|
||||
|
||||
First-wave payload:
|
||||
|
||||
- total included asset count;
|
||||
- one per-asset list with:
|
||||
- `assetId`
|
||||
- `assetName`
|
||||
- `assetFamily`
|
||||
- `minArtifactCount`
|
||||
- `maxArtifactCount`
|
||||
- `lastModified`
|
||||
|
||||
### 2. Validation
|
||||
|
||||
`validation` evaluates the same pack set as `summary`, but its job is to answer a different question:
|
||||
|
||||
Can packing begin?
|
||||
|
||||
First-wave rule:
|
||||
|
||||
- only `blocking` diagnostics fail validation;
|
||||
- warnings are visible elsewhere, but they are not part of the first validation gate contract.
|
||||
|
||||
Primary payload:
|
||||
|
||||
- one per-asset list containing only assets with blocking diagnostics.
|
||||
|
||||
### 3. Pack Execution
|
||||
|
||||
`packWorkspace(...)` is a write-lane operation.
|
||||
It does not trust that earlier summary or validation responses are still current.
|
||||
|
||||
The first-wave execution path is:
|
||||
|
||||
1. create a fresh execution snapshot;
|
||||
2. rerun the gate on that snapshot;
|
||||
3. materialize outputs from frozen in-memory inputs;
|
||||
4. write to `build/.staging/<operation-id>/`;
|
||||
5. promote to final `build/` outputs only after coherent success.
|
||||
|
||||
### 4. Result Semantics
|
||||
|
||||
The final result must distinguish:
|
||||
|
||||
- gate failure before emission;
|
||||
- execution/materialization failure;
|
||||
- persistence/promotion failure;
|
||||
- successful publication.
|
||||
|
||||
Studio should be able to render `Packing` and `Result` from packer-owned outcome semantics alone.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why green validation is not enough
|
||||
|
||||
Validation may have been green a few seconds earlier.
|
||||
If the workspace changes before pack execution begins, the packer still must rerun the gate on a fresh frozen snapshot.
|
||||
|
||||
That protects the operation from:
|
||||
|
||||
- stale UI assumptions;
|
||||
- filesystem drift;
|
||||
- accidental emission from no-longer-valid inputs.
|
||||
|
||||
### Example: Why summary excludes unregistered assets
|
||||
|
||||
The wizard is a pack-set workflow, not a generic workspace inspection screen.
|
||||
Unregistered or excluded assets may matter to other tooling, but they are not explicit summary items in the first-wave wizard contract.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating `summary` as if it were an emitted-artifact preview.
|
||||
- Running validation over a broader set than `registered + included in build`.
|
||||
- Letting non-blocking warnings fail the first-wave validation gate.
|
||||
- Reading live filesystem bytes after frozen execution materialization has started.
|
||||
- Publishing final `build/` outputs before the operation has reached a coherent success point.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../studio/learn/pack-wizard-shell.md`](../../studio/learn/pack-wizard-shell.md)
|
||||
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
88
docs/packer/learn/runtime-ownership-and-studio-boundary.md
Normal file
88
docs/packer/learn/runtime-ownership-and-studio-boundary.md
Normal file
@ -0,0 +1,88 @@
|
||||
# Runtime Ownership and Studio Boundary
|
||||
|
||||
## Original Problem
|
||||
|
||||
Once the packer stopped being just a set of direct filesystem helpers, the repository needed a clear answer for three things:
|
||||
|
||||
1. who owns operational asset semantics;
|
||||
2. how concurrent reads and writes stay coherent;
|
||||
3. how Studio consumes packer state without duplicating domain logic.
|
||||
|
||||
Without that boundary, the system would drift into split-brain behavior between packer services and Studio UI code.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The packer is the semantic owner of operational asset state.
|
||||
Studio is a consumer of packer responses, commands, and events.
|
||||
|
||||
The stable boundary is:
|
||||
|
||||
- filesystem-first authoring workspace;
|
||||
- project-scoped runtime snapshot for reads;
|
||||
- single-writer semantic lane per project for commit-bearing operations;
|
||||
- packer-native observability with causal ordering;
|
||||
- Studio adapters that translate for presentation but do not invent semantics.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Filesystem-First Runtime
|
||||
|
||||
- the workspace on disk remains the durable source of truth;
|
||||
- the runtime snapshot is an operational projection used for coherent reads and write coordination;
|
||||
- divergence between runtime state and filesystem state must become explicit packer state, not silent repair.
|
||||
|
||||
### 2. Concurrency Model
|
||||
|
||||
- `read/read` may run concurrently when both observe one coherent snapshot;
|
||||
- `read/write` must not expose torn intermediate state;
|
||||
- `write/write` on the same project is serialized;
|
||||
- build-bearing operations share the same project-scoped coordination story.
|
||||
|
||||
### 3. Event Ownership
|
||||
|
||||
- packer events are authoritative for lifecycle, progress, and outcomes;
|
||||
- each logical operation carries stable causality through `operation_id` and monotonic `sequence`;
|
||||
- sinks may coalesce noisy progress updates, but terminal lifecycle events remain observable.
|
||||
|
||||
### 4. Studio Adapter Rule
|
||||
|
||||
- Studio may remap packer data into workspace and shell view models;
|
||||
- Studio must not recreate packer summaries, mutation semantics, or reconcile semantics from local heuristics;
|
||||
- adapter code is translational, not semantic-authoritative.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Mutation preview in Studio
|
||||
|
||||
The preview may be rendered in Studio-specific components, but the semantic meaning of:
|
||||
|
||||
- blockers,
|
||||
- warnings,
|
||||
- registry mutations,
|
||||
- filesystem mutations,
|
||||
- final apply outcome
|
||||
|
||||
must still come from the packer.
|
||||
|
||||
### Example: Activity and progress
|
||||
|
||||
If the UI shows a simplified progress bar or activity feed, that is fine.
|
||||
What is not fine is for Studio to infer a successful final outcome without a packer-native terminal event or response.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Rebuilding packer summaries from navigator rows or local filesystem scans.
|
||||
- Treating adapter code as a second owner of mutation or reconcile rules.
|
||||
- Hiding divergence by silently refreshing state without surfacing the transition.
|
||||
- Allowing same-project writes to race because the caller "already validated" earlier.
|
||||
- Collapsing event causality into UI-local state that cannot be replayed or tested outside Studio.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md)
|
||||
116
docs/packer/learn/tile-bank-packing-contract.md
Normal file
116
docs/packer/learn/tile-bank-packing-contract.md
Normal file
@ -0,0 +1,116 @@
|
||||
# Tile Bank Packing Contract
|
||||
|
||||
## Original Problem
|
||||
|
||||
After the generic pack execution boundary was closed, `tile bank` still lacked one explicit producer contract.
|
||||
|
||||
The repository needed to settle:
|
||||
|
||||
1. how selected tile artifacts become one packed payload;
|
||||
2. how palette identity is declared and normalized;
|
||||
3. which runtime fields are derived for `AssetEntry`;
|
||||
4. which structural problems block packing before byte emission.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The first-wave `tile bank` producer contract is:
|
||||
|
||||
1. one canonical `TILES/indexed_v1` payload per asset;
|
||||
2. `1 artifact = 1 tile`;
|
||||
3. artifacts are normalized by explicit `artifacts[*].index`;
|
||||
4. the emitted sheet is fixed at `256 x 256` and row-major;
|
||||
5. tile pixels are packed `u4`;
|
||||
6. bank palettes are emitted as `RGB565` `u16`;
|
||||
7. palette declarations use explicit `{ index, palette }`;
|
||||
8. structural diagnostics are produced early in walker/materialization and therefore participate in validation.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Payload Shape
|
||||
|
||||
The payload is not a concatenation of artifact-local binaries.
|
||||
It is one canonical bank raster:
|
||||
|
||||
1. packed `u4` pixel indices for the full sheet;
|
||||
2. one `64 * 16 * 2` palette block.
|
||||
|
||||
### 2. Artifact and Tile Identity
|
||||
|
||||
- artifacts are normalized by ascending declared `index`;
|
||||
- `tile_id` matches the normalized artifact index;
|
||||
- placement is row-major in the fixed sheet;
|
||||
- v1 capacities depend on `tile_size`:
|
||||
- `8 -> 1024`
|
||||
- `16 -> 256`
|
||||
- `32 -> 64`
|
||||
|
||||
### 3. Palette Contract
|
||||
|
||||
- palette identity is semantic, not positional;
|
||||
- ordering is ascending numeric `index`, never raw list order;
|
||||
- any tile may be rendered with any bank palette at runtime;
|
||||
- palette selection is a draw-time concern, not an embedded per-tile payload field.
|
||||
|
||||
### 4. Metadata Contract
|
||||
|
||||
`AssetEntry.metadata` keeps runtime-required fields readable at the root while preserving segmented subtrees:
|
||||
|
||||
- `output.metadata -> metadata`
|
||||
- `output.codec_configuration -> metadata.codec`
|
||||
- `output.pipeline -> metadata.pipeline`
|
||||
|
||||
For tile banks, that means root readability for values such as:
|
||||
|
||||
- `tile_size`
|
||||
- `width`
|
||||
- `height`
|
||||
- `palette_count`
|
||||
|
||||
### 5. Validation Boundary
|
||||
|
||||
Tile-bank structural issues belong in the walker/materialization path, not in a late pack-only surprise phase.
|
||||
|
||||
Blocking conditions include:
|
||||
|
||||
- duplicate artifact indices;
|
||||
- gaps in normalized artifact indices;
|
||||
- fixed-sheet overflow;
|
||||
- missing palettes;
|
||||
- palette count above `64`;
|
||||
- malformed palette declarations;
|
||||
- missing required metadata;
|
||||
- normalization failure.
|
||||
|
||||
Fragile tile indices are warnings in the first wave, not blockers by themselves.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why palette index must be explicit
|
||||
|
||||
If palette identity depends on array position, a harmless editorial reorder can silently change runtime meaning.
|
||||
|
||||
Using `{ index, palette }` makes semantic identity reviewable and stable.
|
||||
|
||||
### Example: Why validation must see tile-bank structure early
|
||||
|
||||
If duplicate artifact indices are discovered only during final byte emission, the wizard reaches `Packing` too late.
|
||||
The correct behavior is for validation to surface the blocker before emission begins, and for pack execution to rerun that same gate on a fresh execution snapshot.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating artifact declaration order as semantic tile identity.
|
||||
- Packing per-artifact fragments instead of one canonical sheet.
|
||||
- Embedding palette choice per tile in the packed payload.
|
||||
- Flattening all metadata into one ambiguous map.
|
||||
- Discovering tile-bank blockers only during late byte emission.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
|
||||
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
|
||||
@ -1,63 +0,0 @@
|
||||
# PR-01 Packer Project Bootstrap and Module Boundaries
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Create the standalone `prometeu-packer` project and establish the production module boundaries required by the packer specs.
|
||||
|
||||
This PR starts the implementation track without leaking packer behavior into Studio.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver a separate top-level `prometeu-packer` project with build wiring, package boundaries, test harness, and service-facing contracts that future PRs can implement incrementally.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add `prometeu-packer` as a separate project in the repository build
|
||||
- define the baseline package/module layout for:
|
||||
- workspace and registry services
|
||||
- declaration parsing and validation
|
||||
- mutation preview/apply services
|
||||
- build planning and artifact emission
|
||||
- diagnostics and event reporting
|
||||
- define the public service contracts that Studio may consume through adapters
|
||||
- add baseline unit-test and fixture support for packer-only development
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no full workspace semantics yet
|
||||
- no asset build emission yet
|
||||
- no Studio UI changes beyond dependency wiring preparation
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add `prometeu-packer` to Gradle settings and repository build wiring.
|
||||
2. Create baseline package namespaces and service interfaces.
|
||||
3. Establish a packer-owned test fixture layout for workspace samples and artifact assertions.
|
||||
4. Keep Studio integration contract-based so Studio does not depend on filesystem internals.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `prometeu-packer` exists as a separate build target
|
||||
- packer contracts compile without depending on Studio UI classes
|
||||
- future PRs can add implementations without restructuring the project root
|
||||
- packer test infrastructure is usable from the next PR onward
|
||||
|
||||
## Validation
|
||||
|
||||
- build graph includes `prometeu-packer`
|
||||
- baseline compile test for public contracts
|
||||
- fixture-loading smoke test in the new project
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `settings.gradle.kts`
|
||||
- `prometeu-packer/**`
|
||||
- repository build wiring
|
||||
- cross-domain reference: Studio adapter call sites that will later consume packer services
|
||||
@ -1,60 +0,0 @@
|
||||
# PR-02 Workspace Init, Registry, and Identity Foundation
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the packer-owned workspace control model and registry authority in `prometeu-packer`.
|
||||
|
||||
This PR turns the identity and workspace rules into executable code.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver `init_workspace`, registry load/store, identity allocation, and asset-root resolution as the stable foundation for all later packer operations.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-01-packer-project-bootstrap-and-module-boundaries.md`](./PR-01-packer-project-bootstrap-and-module-boundaries.md)
|
||||
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement `init_workspace`
|
||||
- create and validate `assets/.prometeu/index.json`
|
||||
- implement monotonic `asset_id` allocation and persisted allocator state
|
||||
- model `asset_uuid` allocation and persistence
|
||||
- implement root resolution utilities used by future read/write operations
|
||||
- define structural registry errors and missing-root behavior
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no `asset.json` semantic validation beyond what registry ownership requires
|
||||
- no Studio adapter yet
|
||||
- no build artifacts yet
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Implement packer-owned registry models and codecs.
|
||||
2. Add workspace bootstrap behavior for missing control directories.
|
||||
3. Enforce identity invariants around `asset_id`, `asset_uuid`, and root uniqueness.
|
||||
4. Expose internal services for lookup by `asset_id`, `asset_uuid`, and root path.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- workspace initialization creates the minimum control structure deterministically
|
||||
- registry state round-trips without losing allocator data
|
||||
- duplicate or ambiguous identity-bearing entries fail clearly
|
||||
- relocation can later update root location without changing identity fields
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for registry round-trip and allocator monotonicity
|
||||
- unit tests for duplicate-root and malformed-registry failures
|
||||
- workspace-init fixture test
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- `assets/.prometeu/index.json` contract implementation
|
||||
- packer fixture workspaces
|
||||
@ -1,65 +0,0 @@
|
||||
# PR-03 Asset Declaration Parsing, Validation, and Details Contract
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement strict `asset.json` parsing and the packer-side details contract used by both tooling and Studio.
|
||||
|
||||
This PR converts the declaration spec into typed packer models and structured diagnostics.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver strict parse, schema/version checks, common field validation, and a `get_asset_details` response model that Studio can consume through an adapter.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-02-workspace-init-registry-and-identity-foundation.md`](./PR-02-workspace-init-registry-and-identity-foundation.md)
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- parse and validate the common `asset.json` contract
|
||||
- validate required baseline fields:
|
||||
- `schema_version`
|
||||
- `name`
|
||||
- `type`
|
||||
- `inputs`
|
||||
- `output`
|
||||
- `preload`
|
||||
- emit structured diagnostics for parse, structural, and version errors
|
||||
- define the packer `get_asset_details` response model
|
||||
- preserve distinction between valid-orphan declarations and invalid declarations
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no full format-family payload encoding rules
|
||||
- no workspace scan aggregation yet
|
||||
- no mutation apply behavior yet
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Implement typed declaration models and strict decoding.
|
||||
2. Add common semantic validation and diagnostic mapping.
|
||||
3. Define details-response DTOs that preserve both declaration and diagnostic evidence.
|
||||
4. Back the contract with representative valid and invalid fixtures.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- invalid declarations fail with actionable structured diagnostics
|
||||
- valid declarations produce stable typed models
|
||||
- `get_asset_details` can expose declaration, inputs, output, preload, and diagnostics cleanly
|
||||
- unsupported or malformed schema versions surface as explicit failures
|
||||
|
||||
## Validation
|
||||
|
||||
- fixture-driven parser tests
|
||||
- semantic validation tests for required fields
|
||||
- details-response tests for valid, orphan, and invalid declarations
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- packer declaration fixtures
|
||||
- cross-domain reference: Studio asset details adapter inputs
|
||||
@ -1,61 +0,0 @@
|
||||
# PR-04 Workspace Scan, List Assets, and Studio Read Adapter
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the read-side operational surface that turns a filesystem workspace into a packer-owned asset snapshot.
|
||||
|
||||
This PR is the first explicit Studio integration step: Studio stops reading the workspace directly and starts consuming a packer response model through an adapter.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver `list_assets`, wire `get_asset_details` over real workspace scanning, and create the read adapter that maps packer responses to Studio workspace models.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-03-asset-declaration-parsing-validation-and-details-contract.md`](./PR-03-asset-declaration-parsing-validation-and-details-contract.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement workspace scanning for managed assets and orphan anchors
|
||||
- implement `list_assets`
|
||||
- finish real `get_asset_details` on top of packer services
|
||||
- distinguish managed-world structural issues from workspace hygiene findings in read responses
|
||||
- create the Studio read adapter from packer responses to the existing Studio asset workspace models
|
||||
- replace filesystem-specific read code in Studio with the adapter-backed path
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no sensitive mutation apply flows yet
|
||||
- no build pipeline yet
|
||||
- no event lane yet
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Scan `assets/` for anchored roots and reconcile against the registry.
|
||||
2. Produce a structured snapshot for list/details services.
|
||||
3. Implement a Studio adapter that maps packer DTOs into the Studio read model without embedding packer logic in JavaFX.
|
||||
4. Verify that Studio read behavior remains equivalent while packer becomes the source of truth.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `list_assets` returns managed and orphan assets coherently
|
||||
- Studio navigator and details surfaces can run on packer-backed read responses
|
||||
- registry authority remains visible in the mapped Studio state
|
||||
- invalid declarations and missing roots surface through structured diagnostics
|
||||
|
||||
## Validation
|
||||
|
||||
- packer tests for scan reconciliation and orphan detection
|
||||
- adapter tests for mapping list/details responses into Studio models
|
||||
- Studio smoke validation using the packer-backed read path
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- `prometeu-studio/**` read adapters and service wiring
|
||||
- test fixtures shared across packer and Studio integration tests
|
||||
@ -1,78 +0,0 @@
|
||||
# PR-05 Sensitive Mutations, Preview/Apply, and Studio Write Adapter
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the packer-owned preview/apply mutation services and route Studio staged mutations through a write adapter instead of local filesystem rules.
|
||||
|
||||
This PR is where the current Studio staged mutation UI starts executing real packer semantics.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver structured preview/apply services for `register_asset`, `adopt_asset`, `forget_asset`, `remove_asset`, quarantine, and relocation, plus the Studio adapter that maps packer mutation responses into the existing staged mutation UI.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md`](../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement preview/apply service contracts for:
|
||||
- `register_asset`
|
||||
- `adopt_asset`
|
||||
- `forget_asset`
|
||||
- `remove_asset`
|
||||
- `quarantine_asset`
|
||||
- `relocate_asset`
|
||||
- preserve explicit distinction between:
|
||||
- registry mutations
|
||||
- workspace mutations
|
||||
- blockers
|
||||
- warnings
|
||||
- safe fixes
|
||||
- implement mutation serialization rules so conflicting write flows do not race
|
||||
- implement the baseline single-writer semantic lane per project for sensitive mutation apply
|
||||
- create the Studio write adapter for staged mutation preview/apply
|
||||
- replace filesystem-only Studio mutation execution with packer-backed services
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no doctor implementation yet
|
||||
- no build artifact emission yet
|
||||
- no generic cross-workspace mutation framework
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Implement staged intent models and preview/apply response types in the packer.
|
||||
2. Implement mutation handlers on top of registry and workspace services.
|
||||
3. Serialize final mutation apply within a project-scoped write lane while keeping preview generation outside the commit-critical section when safe.
|
||||
4. Add a Studio adapter that converts packer mutation responses into the current staged preview model and forwards packer-native lifecycle events into the Studio event bus.
|
||||
5. Retire duplicated mutation semantics from Studio once the adapter path is stable.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- sensitive mutations run through packer preview/apply services
|
||||
- Studio staged mutation UI no longer owns core mutation semantics
|
||||
- relocation preserves `asset_id` and `asset_uuid`
|
||||
- quarantine is explicit, previewable, and reversible in service semantics
|
||||
- mutation failures remain actionable and structured
|
||||
- conflicting mutation applies on the same project cannot commit concurrently
|
||||
- mutation lifecycle can be surfaced to Studio without Studio inventing semantic outcomes
|
||||
|
||||
## Validation
|
||||
|
||||
- packer tests for each sensitive mutation preview/apply path
|
||||
- packer concurrency tests for same-project conflicting writes
|
||||
- adapter tests for mapping packer responses into Studio preview models
|
||||
- adapter tests for forwarding packer mutation lifecycle events into Studio events
|
||||
- Studio smoke validation for preview/apply against the packer-backed path
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- `prometeu-studio/**` mutation adapter and wiring
|
||||
- mutation fixture workspaces
|
||||
@ -1,60 +0,0 @@
|
||||
# PR-06 Doctor, Diagnostics, and Safe-Fix Baseline
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the baseline doctor and diagnostics model for the production packer.
|
||||
|
||||
This PR is responsible for making the packer operationally useful beyond navigation and mutation flows.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver structured doctor execution with managed-world validation, expanded workspace hygiene scanning, and safe-fix preview/apply where baseline-safe.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement managed-world structural validation
|
||||
- implement expanded workspace hygiene scanning
|
||||
- classify diagnostics by severity and blocking behavior
|
||||
- implement safe mechanical fix flows for baseline-safe cases only
|
||||
- expose doctor responses in structured form for Studio and CI consumption
|
||||
- define evidence and summaries suitable for Activity and inline diagnostics
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no silent destructive repair
|
||||
- no speculative auto-healing of relocational or delete scenarios
|
||||
- no final watch mode yet
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Implement diagnostic producers for registry, declaration, and workspace hygiene findings.
|
||||
2. Implement doctor request modes and safe-fix eligibility checks.
|
||||
3. Model doctor output as structured responses instead of terminal-only text.
|
||||
4. Connect safe-fix preview/apply behavior to the same safety rules used by mutation flows.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- blocking and non-blocking diagnostics are clearly separated
|
||||
- doctor can report on both managed-world validity and broader hygiene issues
|
||||
- safe fixes only exist where the operation is explicitly low-risk
|
||||
- Studio and CI can consume the same doctor response model
|
||||
|
||||
## Validation
|
||||
|
||||
- fixture tests for structural errors and hygiene findings
|
||||
- tests for safe-fix eligibility and refusal paths
|
||||
- adapter tests for Studio diagnostic mapping
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- cross-domain reference: Studio diagnostics and activity consumers
|
||||
- doctor fixtures and expected reports
|
||||
@ -1,62 +0,0 @@
|
||||
# PR-07 Build Plan, Determinism, and Cache-Key Foundation
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the deterministic planning layer that normalizes validated assets into a stable build plan before artifact emission.
|
||||
|
||||
This PR is the boundary between workspace semantics and runtime-facing artifact production.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver a deterministic build planner, canonical header model, preload derivation, and cache-key foundation that later emission and incremental work can trust.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-06-doctor-diagnostics-and-safe-fix-baseline.md`](./PR-06-doctor-diagnostics-and-safe-fix-baseline.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- validate build-eligible managed assets
|
||||
- derive deterministic asset ordering by increasing `asset_id`
|
||||
- build canonical header-side models for:
|
||||
- `asset_table`
|
||||
- `preload`
|
||||
- define payload planning slots and offset planning inputs
|
||||
- compute cache keys from validated effective inputs
|
||||
- emit deterministic in-memory build plans before writing files
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final `assets.pa` file emission yet
|
||||
- no watch mode yet
|
||||
- no format-family semantic expansion beyond what current specs already define
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Normalize validated managed assets into a stable build plan representation.
|
||||
2. Implement canonical JSON serialization rules for header mirrors and planner assertions.
|
||||
3. Compute cache keys only from validated effective inputs.
|
||||
4. Add deterministic tests proving equivalent workspaces produce equivalent plans.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- equivalent inputs produce equivalent build plans
|
||||
- asset ordering is independent from filesystem traversal order
|
||||
- preload derivation matches declaration state deterministically
|
||||
- cache-key inputs are explicit and reproducible
|
||||
|
||||
## Validation
|
||||
|
||||
- determinism tests with reordered filesystem fixtures
|
||||
- canonical-header serialization tests
|
||||
- cache-key stability tests
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- build planning fixtures
|
||||
- future dependency for `build` service and event lane
|
||||
@ -1,63 +0,0 @@
|
||||
# PR-08 assets.pa and Companion Artifact Emission
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement writer-side artifact emission on top of the deterministic build planner.
|
||||
|
||||
This PR turns validated and planned build state into the published packer outputs.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver `build`, `assets.pa`, and the baseline companion artifacts with deterministic ordering and stable writer-side contracts.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07-build-plan-determinism-and-cache-key-foundation.md`](./PR-07-build-plan-determinism-and-cache-key-foundation.md)
|
||||
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement the `build` service
|
||||
- emit `assets.pa`
|
||||
- emit:
|
||||
- `build/asset_table.json`
|
||||
- `build/preload.json`
|
||||
- `build/asset_table_metadata.json`
|
||||
- implement canonical header serialization and file writing
|
||||
- implement payload-region offset materialization from the build plan
|
||||
- expose build summaries and applied-artifact metadata for Studio and CI
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no cartridge assembly
|
||||
- no shipper coupling
|
||||
- no speculative layout optimization beyond deterministic packing
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Convert the build plan into emitted artifact bytes and companion files.
|
||||
2. Preserve header authority and 1:1 mirror rules for companion JSON outputs.
|
||||
3. Add golden fixtures for emitted headers and companion artifacts.
|
||||
4. Keep runtime-facing semantics bounded to writer-side production rules already specified.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `build` produces `assets.pa` and companion artifacts deterministically
|
||||
- companion JSON outputs mirror the runtime header where required
|
||||
- emitted ordering and offsets follow the build plan contract
|
||||
- repeated equivalent builds do not drift
|
||||
|
||||
## Validation
|
||||
|
||||
- golden tests for `assets.pa` envelope and header bytes
|
||||
- golden tests for companion JSON mirrors
|
||||
- repeated-build determinism tests
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- build output fixtures
|
||||
- CI artifact assertions
|
||||
@ -1,83 +0,0 @@
|
||||
# PR-09 Event Lane, Progress, and Studio Operational Integration
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the packer event/reporting lane and bind the production packer service lifecycle into Studio operational surfaces.
|
||||
|
||||
This PR is where Studio stops inferring operational history locally and starts reflecting packer-native lifecycle events.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the structured packer event lane, progress reporting, and adapter/wiring so Studio Activity, progress, and refresh behavior align with real packer execution.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/specs/1. Studio Shell and Workspace Layout Specification.md`](../../studio/specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement the initial structured event set:
|
||||
- `asset_discovered`
|
||||
- `asset_changed`
|
||||
- `diagnostics_updated`
|
||||
- `build_started`
|
||||
- `build_finished`
|
||||
- `cache_hit`
|
||||
- `cache_miss`
|
||||
- `preview_ready`
|
||||
- `action_applied`
|
||||
- `action_failed`
|
||||
- `progress_updated`
|
||||
- define the baseline event envelope with fields equivalent to:
|
||||
- `project_id`
|
||||
- `operation_id`
|
||||
- `sequence`
|
||||
- `kind`
|
||||
- `timestamp`
|
||||
- `summary`
|
||||
- `progress`
|
||||
- `affected_assets`
|
||||
- define event publishing hooks across scan, doctor, mutation, and build flows
|
||||
- implement the Studio adapter from packer events to Studio event bus semantics
|
||||
- align global Activity and progress behavior with packer-native lifecycle updates
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final watch daemon
|
||||
- no remote/shared cache orchestration
|
||||
- no UI redesign
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add event publication points to read, mutation, doctor, and build services.
|
||||
2. Define a packer event sink abstraction so Studio is a consumer, not the owner, of the event model.
|
||||
3. Preserve operation causality with stable `operation_id` plus monotonic per-operation `sequence`.
|
||||
4. Map packer events into existing Studio Activity and progress surfaces through an adapter, with coalescing only for low-value repeated progress-like events.
|
||||
5. Verify that long-running work does not block UI interaction and that terminal lifecycle events remain individually visible.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- packer emits structured lifecycle events across core operations
|
||||
- Studio Activity/progress can be driven from packer-native events
|
||||
- mutation and build flows no longer require Studio-local event invention
|
||||
- event ordering is coherent from the UI perspective
|
||||
- same-operation event ordering is preserved through the Studio adapter
|
||||
- adapters may remap event shapes, but do not invent causal relationships or semantic summaries absent from the packer event stream
|
||||
|
||||
## Validation
|
||||
|
||||
- packer event publication tests
|
||||
- adapter tests from packer events to Studio events
|
||||
- ordering/coalescing tests for progress-heavy operations and terminal lifecycle events
|
||||
- Studio smoke validation for Activity and progress during packer-backed operations
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- `prometeu-studio/**` event adapter and wiring
|
||||
- integration fixtures for long-running operations
|
||||
@ -1,70 +0,0 @@
|
||||
# PR-10 Versioning, Migration, Trust, and Production Gates
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Finish the production track by hardening the packer against version skew, corrupted inputs, and unsupported artifacts, while installing CI and integration gates for the standalone project.
|
||||
|
||||
This PR closes the packer implementation wave with production readiness checks rather than new feature surface.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver explicit version checks, migration ownership behavior, trust-boundary enforcement, and production test gates for `prometeu-packer` and its Studio integration path.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-09-event-lane-progress-and-studio-operational-integration.md`](./PR-09-event-lane-progress-and-studio-operational-integration.md)
|
||||
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement explicit version checking across:
|
||||
- `asset.json`
|
||||
- `index.json`
|
||||
- packer-owned cache/control schemas
|
||||
- `assets.pa` writer-side contract surfaces
|
||||
- implement supported-window failure behavior and migration reporting
|
||||
- enforce conservative trust checks before parse, validation, mutation, and build
|
||||
- add CI gates and end-to-end fixtures for:
|
||||
- read flows
|
||||
- mutation preview/apply flows
|
||||
- doctor
|
||||
- build
|
||||
- Studio adapter integration
|
||||
- consolidate operational docs and production readiness notes for the packer project
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no plugin system
|
||||
- no artifact signing strategy
|
||||
- no remote registry or shared-cache product surface
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add version and migration checks to all packer-owned artifact boundaries.
|
||||
2. Make unsupported-version and migration failures explicit and structured.
|
||||
3. Add end-to-end integration fixtures that exercise the standalone packer with the Studio adapter path.
|
||||
4. Install repository gates so production regressions fail before merge.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- unsupported versions fail early and clearly
|
||||
- migration attempts and failures are visible to Studio and CI
|
||||
- packer trust boundaries are enforced before unsafe work proceeds
|
||||
- `prometeu-packer` has end-to-end production gates covering its declared service surface
|
||||
|
||||
## Validation
|
||||
|
||||
- version-compatibility and migration tests
|
||||
- malformed/untrusted input hardening tests
|
||||
- end-to-end integration tests across packer plus Studio adapter path
|
||||
- CI execution proving the packer project is gated independently
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/**`
|
||||
- repository CI/build configuration
|
||||
- `prometeu-studio/**` integration gates where the adapter path is exercised
|
||||
- packer learn/spec propagation targets after implementation
|
||||
@ -1,194 +0,0 @@
|
||||
# PR-11 Packer Runtime Restructure, Snapshot Authority, and Durable Commit
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The current `prometeu-packer` production track established the packer as the semantic owner of asset state, write semantics, diagnostics, and operational events.
|
||||
|
||||
The next architectural step is to restructure the packer so it behaves like a filesystem-first project-scoped operational runtime for the service surface the Studio actually uses today, rather than a collection of filesystem-per-call services:
|
||||
|
||||
- reads should come from a coherent in-memory snapshot;
|
||||
- writes should execute through a packer-owned write path;
|
||||
- state transitions should be coordinated by the packer, not by incidental caller sequencing;
|
||||
- durable visibility should be defined by commit to disk, not by partially observed intermediate filesystem state;
|
||||
- Studio should remain a frontend consumer of packer-owned read/write/event contracts.
|
||||
|
||||
This is a service-first re-architecture program, not a cosmetic refactor.
|
||||
The likely outcome is a substantial internal rewrite of the packer service layer while preserving and tightening the external semantic contract already defined by the packer specs.
|
||||
|
||||
The current wave is intentionally narrow:
|
||||
|
||||
- build only the embedded service runtime needed by Studio asset management;
|
||||
- remove unused or out-of-scope capabilities from the active code path instead of carrying them forward speculatively;
|
||||
- reintroduce `doctor`, `build/pack`, and background reconcile only when a later concrete service need justifies them.
|
||||
|
||||
This PR is an umbrella planning artifact only.
|
||||
It does not authorize direct implementation work by itself.
|
||||
|
||||
## Objective
|
||||
|
||||
Define and execute a family of packer PRs that turns the packer into a project-scoped runtime with:
|
||||
|
||||
- explicit read and write APIs;
|
||||
- a coherent in-memory project snapshot;
|
||||
- packer-owned threading for state write coordination;
|
||||
- durable commit to workspace files as the persistence boundary;
|
||||
- causality-preserving events for Studio and other tooling consumers;
|
||||
- an aggressively reduced active surface focused on the service capabilities currently consumed by Studio.
|
||||
|
||||
Communication model baseline:
|
||||
|
||||
- request/response is the primary contract for queries and commands;
|
||||
- events are the primary contract for asynchronous lifecycle, progress, divergence, and terminal operation reporting;
|
||||
- synchronous command entrypoints may return a `Future` directly when the caller needs an operation handle for later completion;
|
||||
- long-running command completion may still be observed through causality-preserving events correlated to that operation;
|
||||
- the packer should not use events as a replacement for normal query/command response semantics.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- [`../decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md`](../decisions/Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
|
||||
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
Decision baseline already in place:
|
||||
|
||||
- [`../decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](../decisions/Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)
|
||||
|
||||
This PR is the umbrella execution plan for that direction.
|
||||
It is not a substitute for that decision record and it is not itself an implementation PR.
|
||||
|
||||
## Scope
|
||||
|
||||
- lock the architectural target and implementation decomposition for the runtime-restructure wave
|
||||
- perform cleanup and active-surface reduction before runtime work begins
|
||||
- define a packer-internal project runtime model that owns one coherent state snapshot per active project
|
||||
- define packer-owned read APIs that serve data from the runtime snapshot instead of recomputing the full model from disk for each call
|
||||
- define a packer-owned write lane that executes on packer-controlled threading rather than caller-controlled sequencing
|
||||
- define the durable commit model from in-memory state to workspace files under `assets/` and `assets/.prometeu/`
|
||||
- define snapshot refresh/bootstrap/recovery behavior
|
||||
- define embedded-host bootstrap rules for supplying the explicit `PackerEventSink` used by packer event publication, with host-side bridging to any shared typed event bus
|
||||
- define the query/command versus event boundary for Studio integration
|
||||
- define how synchronous command entrypoints expose `Future`-based completion to callers that need direct operation handles
|
||||
- migrate only the service surface currently used by Studio asset management onto the runtime model
|
||||
- remove or retire implementation paths that are not used by that active service wave
|
||||
- preserve Studio as a consumer of packer responses and events, not an owner of packer semantics
|
||||
- retire the current filesystem-per-call service style once the runtime-backed path is stable
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no direct code implementation inside `PR-11`
|
||||
- no direct rollout of one monolithic runtime rewrite under one follow-up change
|
||||
- no redesign of Studio workspace UX
|
||||
- no remote daemon or IPC transport in this wave
|
||||
- no distributed or multi-process transactional protocol
|
||||
- no final watch-service design for external filesystem edits
|
||||
- no `doctor` implementation in this wave
|
||||
- no `build/pack` implementation in this wave
|
||||
- no background reconcile implementation in this wave
|
||||
- no silent semantic changes to asset identity, registry authority, or write behavior already defined in packer specs
|
||||
- no replacement of the packer event model with Studio-local orchestration
|
||||
|
||||
## Execution Method
|
||||
|
||||
This work must be executed as a family of follow-up PRs.
|
||||
`PR-11` freezes the target architecture and the decomposition logic, but implementation starts only in later PR documents.
|
||||
|
||||
The follow-up implementation PR family is:
|
||||
|
||||
1. [`PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
|
||||
2. [`PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md)
|
||||
3. [`PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
|
||||
4. [`PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
5. [`PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
6. [`PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
|
||||
7. [`PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
|
||||
|
||||
Each follow-up PR should remain granular enough to:
|
||||
|
||||
- have a narrow acceptance surface;
|
||||
- carry its own tests and rollback story;
|
||||
- avoid mixing cleanup, bootstrap, runtime-core, UI-adapter, and deferred capability concerns in one code change.
|
||||
|
||||
Wave discipline for all follow-up PRs:
|
||||
|
||||
- remove code that is not used by the active Studio-facing service wave instead of preserving speculative extension points;
|
||||
- do not reintroduce `doctor`, `build/pack`, or background reconcile as placeholders;
|
||||
- add capabilities later only when the active Studio integration requires them.
|
||||
|
||||
Deferred from the current wave:
|
||||
|
||||
- `doctor`
|
||||
- `build/pack`
|
||||
- background reconcile/diff observer
|
||||
|
||||
Those capabilities should be reintroduced only when the active service wave needs them.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `PR-11` remains an umbrella plan rather than a direct implementation vehicle
|
||||
- the follow-up implementation family is clear enough that later PRs can be opened without reopening the architecture debate
|
||||
- the packer has an explicit project-scoped runtime authority model
|
||||
- read operations observe coherent snapshot state
|
||||
- write operations are executed through packer-owned coordination on packer-controlled threading
|
||||
- durable visibility is defined by successful commit, not by partially observed intermediate filesystem state
|
||||
- same-project write conflicts cannot commit concurrently
|
||||
- same-project read/write interaction does not expose torn committed truth
|
||||
- asset identity, registry authority, and write semantics remain consistent with existing packer specs
|
||||
- the active implementation surface contains only the service capabilities currently used by Studio
|
||||
- unused or out-of-scope legacy capability paths are removed instead of lingering in parallel
|
||||
- Studio consumes packer read/write/event APIs as a frontend consumer and does not regain semantic ownership
|
||||
- request/response remains the primary query/command contract while events remain the asynchronous observability contract
|
||||
- synchronous command APIs may expose `Future` completion directly without collapsing the event lane into ad hoc RPC polling
|
||||
- event ordering and `operation_id` causality remain valid through the restructured runtime
|
||||
- the packer keeps `PackerEventSink` as its publication boundary instead of depending directly on host event bus types
|
||||
- embedded hosts may bridge `PackerEventSink` into a container-owned typed event bus, but the packer API must not normalize a silent `noop` default as production bootstrap behavior
|
||||
|
||||
## Validation
|
||||
|
||||
- snapshot bootstrap tests for projects with valid, invalid, and partially broken asset workspaces
|
||||
- read coherence tests under concurrent read pressure
|
||||
- write serialization tests for same-project conflicting writes
|
||||
- failure and recovery tests for interrupted durable commit paths
|
||||
- write-path regression tests on top of the runtime core for the commands currently used by Studio
|
||||
- cleanup validation proving that inactive `doctor`, `build/pack`, and background reconcile implementation paths are no longer part of the active wave
|
||||
- event ordering and terminal lifecycle tests through the Studio adapter path
|
||||
- Studio smoke validation for:
|
||||
- asset listing
|
||||
- details loading
|
||||
- staged writes
|
||||
- relocation
|
||||
- refresh after packer-owned operations
|
||||
- bootstrap validation that Studio initializes the container-owned typed event bus before packer-backed runtime use
|
||||
|
||||
## Risks and Rollback
|
||||
|
||||
- this program may expose that the current service boundaries are too filesystem-centric to preserve cleanly
|
||||
- removing out-of-scope capabilities now may require later reintroduction work when those capabilities become necessary again
|
||||
- external filesystem edits during runtime lifetime are not fully solved by this plan and must not be hidden as if they were
|
||||
- if runtime-backed services prove too invasive, rollback should preserve the current stable service contracts while isolating the runtime work behind new internal packages until the migration is complete
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/decisions/**`
|
||||
- `docs/packer/pull-requests/**`
|
||||
- `docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`
|
||||
- `docs/packer/specs/1. Domain and Artifact Boundary Specification.md`
|
||||
- `docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`
|
||||
- `docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
||||
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
- `docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md`
|
||||
- `docs/studio/specs/2. Studio UI Foundations Specification.md`
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
||||
- `prometeu-packer/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/src/test/java/p/packer/**`
|
||||
- `prometeu-studio/**` integration adapter and smoke coverage
|
||||
|
||||
## Suggested Next Step
|
||||
|
||||
Do not start code execution directly from this plan.
|
||||
|
||||
The next correct step is to derive granular implementation PRs from `PR-11`, each scoped to one execution front of the runtime-restructure wave.
|
||||
@ -1,74 +0,0 @@
|
||||
# PR-12 Cleanup and Unused Surface Removal Before the Runtime Service Wave
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Before introducing the runtime service wave, the current packer code should be reduced and cleaned so the next PRs are not built on top of contradictory seams.
|
||||
|
||||
The current code still mixes:
|
||||
|
||||
- implicit concrete instantiation inside services;
|
||||
- filesystem-per-call orchestration;
|
||||
- service boundaries that do not match the desired runtime model;
|
||||
- inactive or out-of-scope capabilities that are not part of the immediate Studio-driven service wave.
|
||||
|
||||
This PR creates the cleanup baseline.
|
||||
|
||||
## Objective
|
||||
|
||||
Remove unused/out-of-scope packer surfaces, align code with the current specs, and prepare a smaller active service boundary for the runtime implementation track.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
|
||||
- [`../decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](../decisions/Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- align `asset.json` handling with the current spec baseline, including `asset_uuid`
|
||||
- remove inactive `doctor`, `build/pack`, and reconcile-oriented implementation paths from the active runtime-service wave
|
||||
- remove concrete default instantiation patterns that hide composition ownership
|
||||
- simplify the active service surface to what the current Studio integration actually needs
|
||||
- remove code that is not being used for the immediate service-only wave
|
||||
- correct service contract seams that currently mix read-oriented and mutation-oriented responsibilities in contradictory ways
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no runtime snapshot yet
|
||||
- no write lane yet
|
||||
- no Studio adapter redesign yet
|
||||
- no reintroduction of doctor/build/reconcile in this wave
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Align manifest/declaration code with the current spec baseline.
|
||||
2. Remove inactive service paths that are not part of the current Studio-driven runtime wave.
|
||||
3. Eliminate implicit composition where services instantiate concrete collaborators by default.
|
||||
4. Correct active service contracts so the remaining surface matches the Studio-facing runtime plan.
|
||||
5. Leave the repository with one smaller active surface that the runtime work can replace cleanly.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `asset_uuid` is no longer missing from the active declaration path
|
||||
- inactive `doctor`, `build/pack`, and reconcile implementation paths are removed from the active wave
|
||||
- concrete service composition is no longer hidden behind broad default constructors in the active path
|
||||
- contradictory active service contracts are corrected before runtime work starts
|
||||
- the remaining active surface is focused on the service capabilities the Studio currently needs
|
||||
|
||||
## Validation
|
||||
|
||||
- declaration/parser tests for the manifest baseline
|
||||
- cleanup tests confirming out-of-scope service paths are no longer part of the active surface
|
||||
- regression tests confirming the remaining active service surface still works
|
||||
- smoke validation that Studio-facing packer usage still boots after the cleanup
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/src/test/java/p/packer/**`
|
||||
- `prometeu-studio/**` only where the active service surface changes
|
||||
@ -1,73 +0,0 @@
|
||||
# PR-13 Embedded Bootstrap, Container-Owned Event Bus, and Packer Composition Root
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
After the cleanup baseline, the next step is to make embedded Studio bootstrap explicit and introduce one composition root for the packer.
|
||||
|
||||
This is where the Studio `Container` becomes a contract plus global holder, while the concrete embedded boot and `prometeu-packer-v1` wiring move into the application layer.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the embedded bootstrap contract, explicit `PackerEventSink` wiring, and an explicit `prometeu-packer-api` to `prometeu-packer-v1` composition root for Studio embedding.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/specs/2. Studio UI Foundations Specification.md`](../../studio/specs/2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- define the embedded packer bootstrap contract
|
||||
- define the packer composition root for the active service wave inside the application layer
|
||||
- keep `prometeu-studio` bound only to `prometeu-packer-api`
|
||||
- wire the Studio `Container` contract/holder as the owner of the shared typed event bus reference used by the host-side `PackerEventSink` bridge
|
||||
- ensure application boot installs a `Container` implementation before packer-backed use begins
|
||||
- make the active embedded runtime entrypoint explicit enough that future capabilities do not depend on hidden constructors or side boot paths
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no runtime snapshot yet
|
||||
- no read migration yet
|
||||
- no write lane yet
|
||||
- no alternate bootstrap retained for inactive `doctor`, `build/pack`, or reconcile paths
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the explicit packer bootstrap/composition entrypoint.
|
||||
2. Make the host-provided `PackerEventSink` an explicit dependency for Studio embedding.
|
||||
3. Refactor Studio `Container` into a contract plus installed global holder.
|
||||
4. Move concrete packer wiring to the application layer that chooses `prometeu-packer-v1`.
|
||||
5. Remove remaining ambiguity around packer-local versus container-owned event visibility by bridging `PackerEventSink` into the host bus at the application layer.
|
||||
5. Remove remaining embedded bootstrap variants that only exist to keep inactive service surfaces alive.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the active packer wave has one explicit composition root
|
||||
- `prometeu-studio` depends only on `prometeu-packer-api`
|
||||
- the application layer installs the `Container` implementation and chooses `prometeu-packer-v1`
|
||||
- Studio `Container` owns the shared typed event bus reference through its installed implementation
|
||||
- the packer composition root receives an explicit `PackerEventSink` rather than reaching directly into host event bus types
|
||||
- packer-backed work starts only after `Container.install(...)`
|
||||
- packer publication uses `PackerEventSink`, and the application layer bridges that sink into the container-owned path when embedded in Studio
|
||||
- no public `PackerEventSink.noop()`-style default is treated as acceptable production bootstrap behavior
|
||||
- hidden bootstrap paths that only support inactive service surfaces are removed
|
||||
|
||||
## Validation
|
||||
|
||||
- bootstrap tests for the packer composition root
|
||||
- Studio boot tests for `Container.install(...)`
|
||||
- integration tests for packer event visibility through the host bridge into the container-owned path
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/Container.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/**`
|
||||
- `prometeu-app/src/main/java/p/studio/App.java`
|
||||
- `prometeu-app/src/main/java/p/studio/AppContainer.java`
|
||||
@ -1,68 +0,0 @@
|
||||
# PR-14 Project Runtime Core, Snapshot Model, and Lifecycle
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
With cleanup and bootstrap in place, the packer can now introduce the actual project runtime.
|
||||
|
||||
This PR adds the runtime boundary, snapshot state model, bootstrap/load behavior, and disposal lifecycle that later query and command services will use.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the project-scoped runtime core and one coherent in-memory snapshot model for the active service wave.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
|
||||
- [`./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add the project runtime abstraction
|
||||
- define snapshot content and generation ownership only for the active service wave
|
||||
- define runtime bootstrap/load and disposal behavior
|
||||
- isolate filesystem repositories behind the runtime boundary
|
||||
- keep snapshot scope limited to the data needed by the active Studio-facing service path
|
||||
- keep the runtime implementation inside `prometeu-packer-v1` while preserving the external contract in `prometeu-packer-api`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no Studio adapter work yet
|
||||
- no doctor/build/reconcile functionality
|
||||
- no full query migration yet
|
||||
- no write lane yet
|
||||
- no speculative snapshot fields for capabilities that are not part of the active wave
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce project runtime state/container types.
|
||||
2. Load registry plus asset declarations into the runtime snapshot.
|
||||
3. Define runtime generation, refresh, and disposal rules.
|
||||
4. Keep the runtime state minimal and aligned with the currently used service surface.
|
||||
5. Make later query/command work depend on this runtime boundary rather than direct filesystem scans.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- one coherent runtime exists per active project
|
||||
- runtime bootstrap/load is explicit and testable
|
||||
- runtime disposal is explicit
|
||||
- filesystem repositories are isolated behind the runtime boundary
|
||||
- runtime state is limited to what the active Studio service wave actually consumes
|
||||
|
||||
## Validation
|
||||
|
||||
- runtime bootstrap tests
|
||||
- snapshot generation tests
|
||||
- lifecycle tests for bootstrap, refresh, and disposal
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
|
||||
@ -1,70 +0,0 @@
|
||||
# PR-15 Snapshot-Backed Asset Query Services
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The first functional runtime-backed service wave should focus on queries.
|
||||
|
||||
This PR moves the asset query surface used by Studio onto the runtime snapshot and defines coherent query behavior without expanding into doctor/build/reconcile.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver snapshot-backed query services for the currently used asset-management surface.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- migrate `init_workspace`
|
||||
- migrate `list_assets`
|
||||
- migrate `get_asset_details`
|
||||
- keep the query path coherent through the runtime snapshot
|
||||
- preserve the packer-owned summary/details contract used by Studio
|
||||
- remove leftover query orchestration that only existed to feed inactive `doctor`, `build/pack`, or reconcile flows
|
||||
- preserve the modular boundary where `prometeu-studio` consumes only `prometeu-packer-api`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no command/write lane yet
|
||||
- no mutation apply yet
|
||||
- no doctor/build/reconcile
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Route the active query APIs through the runtime snapshot.
|
||||
2. Preserve coherent results across repeated query use.
|
||||
3. Remove repeated recomputation from the active query path.
|
||||
4. Remove active query seams that only support deferred capabilities.
|
||||
5. Keep Studio-facing response semantics stable.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- active asset queries are served from the runtime snapshot
|
||||
- normal query use no longer depends on full filesystem recomputation
|
||||
- Studio-facing details/listing semantics remain stable
|
||||
- no doctor/build/reconcile behavior is introduced by this PR
|
||||
- unused query seams kept only for deferred capabilities are removed from the active path
|
||||
|
||||
## Validation
|
||||
|
||||
- regression tests for `init_workspace`
|
||||
- regression tests for `list_assets`
|
||||
- regression tests for `get_asset_details`
|
||||
- Studio smoke validation for list/details loading
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
|
||||
- `prometeu-studio/**` query adapter coverage
|
||||
@ -1,71 +0,0 @@
|
||||
# PR-16 Write Lane, Command Completion, and Used Write Services
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
After queries are runtime-backed, the next step is the minimal command surface actually used by Studio.
|
||||
|
||||
This PR introduces the project write lane, synchronous command completion semantics, and the write services currently needed by Studio, without reintroducing doctor, build, or reconcile work.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the write lane plus only the write/command surface currently exercised by the Studio `Assets` workspace on top of the runtime model.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`../decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md`](../decisions/Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement the project-scoped write lane
|
||||
- define durable visibility after successful commit
|
||||
- define request/response command semantics with optional `Future`-based completion
|
||||
- implement only the write surface currently used by Studio `Assets`
|
||||
- preserve causal lifecycle events for command execution
|
||||
- reintroduce command/write support in `prometeu-packer-v1` without collapsing the `prometeu-packer-api` boundary
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no doctor
|
||||
- no build/pack
|
||||
- no background reconcile observer
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add the runtime-backed write lane.
|
||||
2. Define synchronous command response plus optional `Future` completion semantics.
|
||||
3. Reintroduce only the currently used write services onto the runtime.
|
||||
4. Remove command surfaces that remain out of scope for the active Studio service wave.
|
||||
5. Preserve asynchronous lifecycle events as observability, not as the primary command contract.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- same-project commands are serialized by the packer
|
||||
- committed state becomes visible only after successful durable commit
|
||||
- synchronous command APIs may expose `Future` completion directly
|
||||
- the write services currently used by Studio run on the runtime-backed path
|
||||
- no doctor/build/reconcile behavior is introduced by this PR
|
||||
- deferred command surfaces are not kept alive in the active implementation by placeholder adapters
|
||||
|
||||
## Validation
|
||||
|
||||
- write-lane concurrency tests
|
||||
- commit failure/recovery tests
|
||||
- command completion tests for response plus `Future`
|
||||
- write regression tests for the active Studio write surface
|
||||
- negative validation proving `doctor`, `build/pack`, and reconcile command paths are not part of the active wave
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
|
||||
- `prometeu-studio/**` command integration coverage
|
||||
@ -1,73 +0,0 @@
|
||||
# PR-17 Studio Runtime Adapter and Assets Workspace Consumption
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Once the active query and command surface is runtime-backed, Studio should consume that path as a frontend without recreating packer semantics.
|
||||
|
||||
This PR hardens the Studio adapters and the `Assets` workspace consumption path for the service-only wave while preserving the modular split between `prometeu-packer-api`, `prometeu-packer-v1`, `prometeu-studio`, and `prometeu-app`.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the Studio-side adapter and `Assets` workspace integration for the active runtime-backed service surface.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md)
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
- cross-domain reference: [`../../studio/specs/2. Studio UI Foundations Specification.md`](../../studio/specs/2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- adapt Studio to consume runtime-backed packer queries and commands
|
||||
- preserve `request/response` as the primary integration model
|
||||
- consume packer lifecycle events through the host bridge from `PackerEventSink` into the container-owned typed event bus path
|
||||
- keep the `Assets` workspace aligned with the active service-only wave
|
||||
- remove adapter branches that only exist for inactive `doctor`, `build/pack`, or reconcile usage
|
||||
- keep `prometeu-studio` bound only to `prometeu-packer-api`
|
||||
- let `prometeu-app` remain responsible for installing the concrete `Container` implementation, applying the `p.packer.Packer` entrypoint from `prometeu-packer-v1`, and bridging `PackerEventSink` into the host bus
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no doctor UI
|
||||
- no pack/build UI
|
||||
- no reconcile-state UI beyond what the current service wave actually exposes
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update the Studio adapter layer to consume the runtime-backed service path.
|
||||
2. Preserve translational mapping only.
|
||||
3. Validate that `prometeu-studio` does not depend on `prometeu-packer-v1` classes directly.
|
||||
4. Validate command submission plus event-driven lifecycle visibility through the host `PackerEventSink` bridge and shared bus path.
|
||||
4. Remove adapter branches that only keep deferred capabilities artificially wired.
|
||||
5. Keep the `Assets` workspace focused on the currently active service surface.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Studio remains a consumer of packer runtime semantics
|
||||
- `Assets` workspace list/details/actions run through the active runtime-backed service path
|
||||
- command submission plus event observation are coherent end to end
|
||||
- no inactive doctor/build/reconcile surfaces are reintroduced
|
||||
- Studio adapters no longer preserve dead branches for deferred capability families
|
||||
- `prometeu-studio` depends only on `prometeu-packer-api`
|
||||
- `prometeu-app` is the layer that binds the concrete `Container` implementation and the `p.packer.Packer` entrypoint from `prometeu-packer-v1`
|
||||
- Studio consumes packer lifecycle visibility through a host-provided `PackerEventSink` bridge rather than by exposing host bus types inside packer contracts
|
||||
|
||||
## Validation
|
||||
|
||||
- Studio adapter tests
|
||||
- `Assets` workspace smoke tests
|
||||
- end-to-end tests for list/details/write flows used by Studio
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/**`
|
||||
- `prometeu-studio/src/test/java/p/studio/**`
|
||||
- `prometeu-app/src/main/java/p/studio/**`
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` integration-facing contracts
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` embedded runtime implementation surfaces
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**` embedded runtime event surfaces
|
||||
@ -1,66 +0,0 @@
|
||||
# PR-18 Legacy Service Retirement and Regression Hardening
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
After the active service-only wave is fully running through the runtime path, the repository should not keep duplicated legacy orchestration around as a competing semantic track.
|
||||
|
||||
This PR retires the superseded legacy paths and hardens regression coverage around the smaller active service surface.
|
||||
It also closes the cleanup promise from `PR-12` by ensuring no unused packer capability families survive just because they existed before the runtime service wave.
|
||||
|
||||
## Objective
|
||||
|
||||
Remove superseded legacy service paths and strengthen regression protection for the runtime-backed service wave.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- retire duplicated filesystem-per-call paths superseded by the active runtime-backed service wave
|
||||
- remove temporary shims that were tolerated only during the migration window
|
||||
- harden regression coverage around the remaining active service surface
|
||||
- remove leftover inactive `doctor`, `build/pack`, and reconcile code that no longer belongs to the service-only wave
|
||||
- preserve the `prometeu-packer-api` surface as the stable consumer contract while retiring legacy implementation paths in `prometeu-packer-v1`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no doctor reintroduction
|
||||
- no build/pack reintroduction
|
||||
- no reconcile observer work
|
||||
- no new architecture decisions
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Remove superseded legacy paths.
|
||||
2. Remove temporary migration shims once the runtime-backed path is complete.
|
||||
3. Simplify the active service composition around the runtime boundary.
|
||||
4. Strengthen regression coverage around the remaining service wave.
|
||||
5. Verify no split-brain semantics remain between active and legacy paths.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- superseded legacy paths are removed
|
||||
- the active runtime-backed service wave is the only semantic path for the currently used functionality
|
||||
- regression coverage protects the reduced active surface
|
||||
- no inactive capability family survives in code solely as speculative future support
|
||||
|
||||
## Validation
|
||||
|
||||
- full active-service regression suite
|
||||
- Studio embedding regression suite
|
||||
- targeted tests proving no disagreement remains between active and legacy paths
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**`
|
||||
- integration fixtures
|
||||
@ -1,98 +0,0 @@
|
||||
# PR-19 API Surface Audit, Model Separation, and Public Read DTOs
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The current packer API still exposes some read payload types that are simultaneously acting as public transport objects and internal implementation models.
|
||||
|
||||
This is acceptable during early convergence, but it weakens the boundary between `prometeu-packer-api` and `prometeu-packer-v1`.
|
||||
|
||||
The next cleanup step is to make the API explicit about three different categories:
|
||||
|
||||
- domain contracts,
|
||||
- request/response messages,
|
||||
- public read DTOs.
|
||||
|
||||
At the same time, the internal implementation models used by `prometeu-packer-v1` should stop leaking through the API as if they were stable public models.
|
||||
|
||||
## Objective
|
||||
|
||||
Separate internal `v1` read models from public API read DTOs while preserving:
|
||||
|
||||
- request/response messages as immutable messages,
|
||||
- domain contracts as domain contracts,
|
||||
- exceptions as part of the public API,
|
||||
- and Studio compatibility through explicit mapper-based conversion inside `prometeu-packer-v1`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
|
||||
- [`./PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- audit the current public packer API against real external consumption
|
||||
- preserve public exceptions in the API even when only `v1` currently throws them
|
||||
- preserve request/response records as request/response messages rather than renaming them as generic DTOs
|
||||
- move the current mixed model/transport read types out of the API and into `prometeu-packer-v1`
|
||||
- introduce public read DTOs in the API for the information Studio actually consumes
|
||||
- add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs
|
||||
- keep the active service wave limited to `initWorkspace`, `listAssets`, `getAssetDetails`, and `createAsset`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no new packer capabilities
|
||||
- no write API redesign
|
||||
- no doctor or build/pack reintroduction
|
||||
- no reconcile observer work
|
||||
- no semantic change to asset identity, registry ownership, or snapshot authority
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Classify the current API surface into:
|
||||
- public domain contracts,
|
||||
- public request/response messages,
|
||||
- public read DTOs,
|
||||
- internal implementation models.
|
||||
2. Keep domain contracts in `prometeu-packer-api` without `DTO` suffixes.
|
||||
3. Keep request/response types in `prometeu-packer-api` as immutable message records with `Request` and `Response` naming.
|
||||
4. Move the current mixed read shapes now exposed as `PackerAssetSummary`, `PackerAssetDetails`, and `PackerAssetIdentity` into `prometeu-packer-v1` as internal models.
|
||||
5. Introduce explicit public DTOs in the API for runtime-backed read payloads, such as:
|
||||
- `PackerAssetSummaryDTO`
|
||||
- `PackerAssetDetailsDTO`
|
||||
- `PackerAssetIdentityDTO`
|
||||
- `PackerCodecConfigurationFieldDTO`
|
||||
- and `PackerDiagnosticDTO` if diagnostics remain part of public responses.
|
||||
6. Add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs before responses cross the module boundary.
|
||||
7. Update response messages to carry the new DTO types instead of leaking `v1` models through the API.
|
||||
8. Update Studio consumers to read from the new DTO types while preserving the same user-facing behavior.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the API surface is explicitly partitioned between domain contracts, request/response messages, and read DTOs
|
||||
- request/response messages remain immutable message records and are not renamed as generic DTOs
|
||||
- public exceptions remain in the API
|
||||
- internal `v1` models are no longer exposed as if they were public API models
|
||||
- Studio depends only on API contracts and DTOs, not on `v1` model semantics
|
||||
- conversion from `v1` internal models to public API DTOs happens through explicit mapper code
|
||||
- no behavior regression is introduced in `initWorkspace`, `listAssets`, `getAssetDetails`, or `createAsset`
|
||||
|
||||
## Validation
|
||||
|
||||
- compile-time audit proving `prometeu-studio` and `prometeu-app` consume only API contracts
|
||||
- packer regression tests for read and write flows
|
||||
- Studio regression tests for asset list, asset details, and add asset flows
|
||||
- targeted tests for mapper coverage between internal models and public API DTOs
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/**`
|
||||
- `prometeu-studio/src/test/java/p/studio/**`
|
||||
|
||||
@ -1,101 +0,0 @@
|
||||
# PR-20 Asset Action Capabilities and Register-First Delivery
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The current `Assets` workspace still decides too much locally about which asset actions should appear and when they should be allowed.
|
||||
|
||||
That is the wrong long-term boundary.
|
||||
|
||||
The packer already owns asset semantics, registration state, build participation, and write execution. It should also own the capability decision for asset actions, while Studio remains a consumer that renders the actions exposed by the service.
|
||||
|
||||
This PR introduces a capability-based action contract driven by the packer, with `AssetAction.REGISTER` as the first delivered action end to end.
|
||||
|
||||
## Objective
|
||||
|
||||
Add a packer-owned asset action capability API and deliver the first action, `REGISTER`, through the full packer-to-Studio path.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
|
||||
- [`./PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.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)
|
||||
|
||||
## Scope
|
||||
|
||||
- define a public packer action contract for asset capabilities
|
||||
- let the packer decide which actions are available for a given asset at a given moment
|
||||
- let Studio render the action section from packer-provided capabilities instead of local semantic rules
|
||||
- keep the capability contract stable even if the packer later moves to FSM or another internal decision model
|
||||
- deliver `AssetAction.REGISTER` as the first supported action end to end
|
||||
- keep the service-only wave focused on active functionality
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no FSM implementation
|
||||
- no full action family rollout in the first delivery
|
||||
- no doctor/build/reconcile action surfaces
|
||||
- no speculative future actions without packer support
|
||||
- no frontend-local capability engine
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a public action capability contract in `prometeu-packer-api`, including:
|
||||
- `AssetAction` enum
|
||||
- capability response shape for asset actions
|
||||
- request/response messages for reading action capabilities
|
||||
2. Model the response so the packer can expose at least:
|
||||
- `action`
|
||||
- `enabled`
|
||||
- `visible`
|
||||
- optional `reason`
|
||||
3. Add a runtime-backed read path in `prometeu-packer-v1` that resolves action capabilities from the current asset state.
|
||||
4. Keep the internal decision logic inside the packer implementation. Studio must not reconstruct capability semantics.
|
||||
5. Add a write path for `AssetAction.REGISTER`.
|
||||
6. Expose `REGISTER` only when the asset capability resolver says it is allowed.
|
||||
7. Render the `Actions` section in Studio from the returned capabilities.
|
||||
8. Execute `REGISTER` from Studio through the packer write path and refresh the asset workspace after completion.
|
||||
|
||||
## Register-First Delivery Rules
|
||||
|
||||
The first delivered action is:
|
||||
|
||||
- `AssetAction.REGISTER`
|
||||
|
||||
Expected initial capability behavior:
|
||||
|
||||
- unregistered assets may expose `REGISTER`
|
||||
- registered assets must not expose `REGISTER`
|
||||
- Studio must only show the `Register` button when the packer returns that capability
|
||||
|
||||
Other future actions such as `MOVE`, `DELETE`, `INCLUDE_IN_BUILD`, `EXCLUDE_FROM_BUILD`, `ENABLE_PRELOAD`, `DISABLE_PRELOAD`, and `CHANGE_CONTRACT` are intentionally deferred from code delivery in this PR unless needed to support the contract shape.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the packer API exposes an asset action capability contract
|
||||
- Studio reads action capabilities from the packer instead of deciding them locally
|
||||
- the first delivered action is `AssetAction.REGISTER`
|
||||
- `REGISTER` is available only for unregistered assets
|
||||
- `REGISTER` is not shown for registered assets
|
||||
- Studio can trigger `REGISTER` through the packer service path and refresh the workspace after success
|
||||
- the capability contract remains valid if packer internals later migrate to FSM or another orchestration model
|
||||
|
||||
## Validation
|
||||
|
||||
- packer unit tests for capability resolution
|
||||
- packer tests for `REGISTER` execution
|
||||
- Studio tests or smoke tests proving that action buttons are rendered from service-provided capabilities
|
||||
- end-to-end validation for unregistered asset -> register -> refresh -> registered asset
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/**`
|
||||
- `prometeu-studio/src/test/java/p/studio/**`
|
||||
|
||||
@ -1,77 +0,0 @@
|
||||
# PR-21 Point In-Memory Snapshot Updates After Write Commit
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The current write path still rebuilds the whole project runtime snapshot after a successful point write such as `REGISTER`.
|
||||
|
||||
That is too expensive for the runtime model we want.
|
||||
|
||||
Studio refresh on top of an already-updated in-memory snapshot is acceptable. Full filesystem rescan inside the packer after every point write is not.
|
||||
|
||||
This PR replaces the normal post-write `full refresh` path with point snapshot updates in memory, while keeping full reload available only as an explicit recovery fallback.
|
||||
|
||||
## Objective
|
||||
|
||||
Remove whole-project runtime rescan from the normal point write path and replace it with point in-memory snapshot updates after durable commit.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add explicit point snapshot update support to the runtime registry
|
||||
- keep the write lane as the only owner of point runtime mutation after durable commit
|
||||
- replace post-write `runtimeRegistry.refresh(project)` in the active write path with point snapshot patching
|
||||
- deliver the first point patch for `REGISTER`
|
||||
- keep Studio refresh behavior unchanged
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no background divergence detection
|
||||
- no reconcile loop
|
||||
- no change to Studio refresh semantics
|
||||
- no broad event model redesign
|
||||
- no speculative patch implementation for unused write actions
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Extend the runtime registry so it can update a loaded project snapshot by applying a point patch function inside the packer-owned write flow.
|
||||
2. Keep full snapshot reload available as recovery fallback, but do not use it in the normal successful point write path.
|
||||
3. Model a point patch for `REGISTER` that:
|
||||
- appends the new registry entry to the in-memory registry view
|
||||
- updates the matching runtime asset from unregistered to registered
|
||||
- preserves the rest of the snapshot untouched
|
||||
4. Apply the patch only after the durable disk commit succeeds.
|
||||
5. Keep read services unchanged from the Studio point of view; they should continue reading from the runtime snapshot.
|
||||
6. Keep Studio free to refresh list/details after write completion, because those reads now hit the already-updated in-memory snapshot.
|
||||
7. Add regression coverage proving that `REGISTER` no longer depends on whole-project rescan to become visible to subsequent reads.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- successful point writes no longer trigger whole-project runtime rescan in the normal path
|
||||
- the runtime registry supports point in-memory snapshot updates after durable commit
|
||||
- `REGISTER` updates the loaded project snapshot in place
|
||||
- subsequent `listAssets`, `getAssetDetails`, and `getAssetActions` read the updated state from memory
|
||||
- Studio refresh after `REGISTER` remains valid and does not require frontend-local state patching
|
||||
- full reload remains available only as fallback or explicit recovery path
|
||||
|
||||
## Validation
|
||||
|
||||
- packer tests for point snapshot patching on `REGISTER`
|
||||
- packer tests proving read-after-write coherence without full runtime rebuild
|
||||
- regression tests for fallback safety when point patching cannot be applied
|
||||
- Studio smoke validation confirming existing refresh behavior still works on top of the updated runtime snapshot
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/**`
|
||||
@ -1,77 +0,0 @@
|
||||
# PR-22 Delete Asset Action Confirmation and Fs-First Manifest Removal
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The action capability contract introduced in `PR-20` needs its next real delivery beyond `REGISTER`.
|
||||
|
||||
`DELETE` must remove the asset from packer control without deleting the asset directory or its remaining files. The operation is filesystem-first: delete `asset.json`, update `index.json` when needed, and then apply a point snapshot update in memory.
|
||||
|
||||
Studio must require explicit confirmation before calling this write path.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver `AssetAction.DELETE` end to end with packer-owned capability resolution, Studio confirmation modal, filesystem-first manifest removal, and point runtime snapshot update.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
|
||||
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- extend the public action contract with `DELETE`
|
||||
- expose `DELETE` capability from the packer for assets that currently own `asset.json`
|
||||
- add a packer write path that deletes only `asset.json`
|
||||
- remove any registered entry from `index.json`
|
||||
- keep the asset directory and its non-manifest files on disk
|
||||
- patch the loaded runtime snapshot in memory after successful delete
|
||||
- add a Studio modal that requires typing the asset name before confirming deletion
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no recursive directory deletion
|
||||
- no deletion of companion files or arbitrary asset contents
|
||||
- no frontend-local action capability rules
|
||||
- no bulk delete
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Extend the action enum and packer API with `DELETE` and its write message/response.
|
||||
2. Add packer capability resolution for `DELETE` based on `asset.json` presence, independent from declaration validity.
|
||||
3. Implement `deleteAsset` in the packer write lane.
|
||||
4. Make the write path:
|
||||
- resolve the asset
|
||||
- delete `asset.json`
|
||||
- remove the registry entry when the asset is registered
|
||||
- keep the asset directory and any remaining files untouched
|
||||
- patch the in-memory snapshot by removing the asset from runtime view
|
||||
5. Add a Studio confirmation modal that requires the user to type the asset name exactly.
|
||||
6. On success, let Studio refresh and clear the current selection.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `DELETE` is exposed through the packer action capability contract
|
||||
- Studio renders `DELETE` only from packer-provided capabilities
|
||||
- Studio requires asset-name confirmation before executing `DELETE`
|
||||
- `DELETE` removes only `asset.json`
|
||||
- registered assets are also removed from `index.json`
|
||||
- the asset directory and remaining files stay on disk
|
||||
- the runtime snapshot is updated in memory without whole-project reload in the normal path
|
||||
|
||||
## Validation
|
||||
|
||||
- packer tests for `DELETE` capability visibility
|
||||
- packer tests for deleting registered and unregistered assets
|
||||
- packer tests proving directory contents remain on disk after delete
|
||||
- Studio compile/test validation for the confirmation modal and action wiring
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/**`
|
||||
- `prometeu-studio/src/main/resources/**`
|
||||
@ -1,101 +0,0 @@
|
||||
# PR-23 Move Asset Action Wizard and Fs-First Relocation
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The action capability track already delivers `REGISTER` and `DELETE`.
|
||||
|
||||
The next operational action is `MOVE`, which must let the user relocate an asset root inside the project's `assets/` tree and optionally rename the asset directory in the same flow.
|
||||
|
||||
Studio should own the wizard and the interaction flow. The packer should own the validation semantics, the filesystem move, the registry update, and the point snapshot patch after durable commit.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver `AssetAction.MOVE` end to end with a Studio relocation wizard, packer-owned constraints, filesystem-first directory move, and minimal in-memory snapshot update.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
|
||||
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
|
||||
- [`./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md`](./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- extend the public action contract and write messages for `MOVE`
|
||||
- expose `MOVE` capability from the packer
|
||||
- add a Studio wizard that collects:
|
||||
- destination parent directory
|
||||
- destination directory name
|
||||
- derived target root inside `assets/`
|
||||
- add a confirmation step before execution
|
||||
- add an execution/waiting step with spinner while the move is running
|
||||
- allow the wizard to work as both relocate and rename of the asset directory
|
||||
- enforce packer constraints that:
|
||||
- the target must stay inside the project's `assets/`
|
||||
- the target root must not already contain `asset.json`
|
||||
- perform the actual move in the filesystem inside the packer write lane
|
||||
- update `index.json` and patch the runtime snapshot minimally after commit
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no move outside the project's `assets/`
|
||||
- no directory merge behavior
|
||||
- no recursive validation of non-manifest file contents
|
||||
- no batch move
|
||||
- no frontend-local move semantics
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Extend the action contract with `MOVE` and add write request/response messages for asset relocation.
|
||||
2. Add packer capability resolution for `MOVE`.
|
||||
3. Build a Studio wizard dedicated to move/rename, with:
|
||||
- current asset root display
|
||||
- destination parent picker constrained to `assets/`
|
||||
- destination directory name field
|
||||
- derived target root preview
|
||||
- validation feedback
|
||||
- confirmation step before submit
|
||||
- waiting state with spinner after submit until the write result is known
|
||||
4. Enforce these constraints in the packer:
|
||||
- the target root must remain under `assets/`
|
||||
- the target root must not already contain `asset.json`
|
||||
5. Execute the move in the packer write lane by:
|
||||
- moving the asset directory in the filesystem
|
||||
- updating the registry entry root when the asset is registered
|
||||
- preserving `asset_uuid`
|
||||
6. Patch the runtime snapshot in memory after the move, without whole-project reload in the normal path.
|
||||
7. Let Studio refresh and reselect the moved asset after success.
|
||||
8. Keep the wizard open in waiting state while the move is running, then close only after success; on failure, leave the wizard recoverable with feedback.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `MOVE` is exposed through the packer action capability contract
|
||||
- Studio opens a wizard for `MOVE`
|
||||
- the wizard has an explicit confirmation step before execution
|
||||
- the wizard enters a waiting state with spinner while the move is in flight
|
||||
- the wizard lets the user relocate and/or rename the asset directory
|
||||
- the move target cannot be outside the project's `assets/`
|
||||
- the move target cannot already contain `asset.json`
|
||||
- the packer performs the filesystem move
|
||||
- `index.json` is updated when needed
|
||||
- the runtime snapshot is patched minimally after success
|
||||
- Studio refreshes and keeps the moved asset selected
|
||||
|
||||
## Validation
|
||||
|
||||
- packer tests for move capability visibility
|
||||
- packer tests for successful relocate and successful rename
|
||||
- packer tests for blockers when target is outside `assets/`
|
||||
- packer tests for blockers when target already contains `asset.json`
|
||||
- packer tests proving snapshot patching after move
|
||||
- Studio smoke validation for wizard confirmation flow, waiting state, and post-move reselection
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/**`
|
||||
- `prometeu-studio/src/main/resources/**`
|
||||
@ -1,200 +0,0 @@
|
||||
# PR-24 Asset File Cache Hydration and Walker Reuse
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The runtime loader already walks asset roots and produces `walkResult`, and `PackerWorkspacePaths` already reserves `assets/.prometeu/cache.json`.
|
||||
|
||||
What is still missing is the actual cache lifecycle:
|
||||
|
||||
- previous cache is not loaded before a walk;
|
||||
- walkers do not receive prior file facts for comparison;
|
||||
- `walkResult` does not become a durable cache artifact after the scan.
|
||||
|
||||
That leaves the current runtime path unable to reuse prior file knowledge such as `lastModified`, `size`, `fingerprint`, and family-specific probe metadata.
|
||||
|
||||
This PR introduces the first durable asset file cache flow for the runtime-backed packer wave.
|
||||
It also tightens how walk output becomes part of the runtime snapshot and how diagnostics are split between normal aggregated surfaces and file-scoped UI-facing surfaces.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver an asset-scoped file cache stored in `assets/.prometeu/cache.json`, hydrated before the runtime walk and refreshed from the current `walkResult` after the walk completes, while also attaching the current `walkResult` to the runtime snapshot.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- define the durable schema for `assets/.prometeu/cache.json`
|
||||
- store cache entries per asset and per discovered file, not as one flat global fingerprint bag
|
||||
- restrict cache and internal file walk analysis to assets that are already registered and therefore have stable `asset_id`
|
||||
- load prior cache state during runtime snapshot bootstrap and refresh
|
||||
- pass prior asset-scoped cache entries into the asset walker
|
||||
- let walkers compare current file observations against prior cached facts such as `lastModified`, `size`, `fingerprint`, and family-specific metadata
|
||||
- treat the current `walkResult` as the source used to build the next durable cache state
|
||||
- attach the current `walkResult` to the in-memory runtime snapshot for later query and UI use
|
||||
- persist refreshed cache after a successful runtime load or write-path point patch that recomputes asset content
|
||||
- keep cache miss, corruption, or version mismatch non-fatal for normal asset reads
|
||||
- keep the Studio-visible asset query surface stable while the cache becomes an internal optimization and comparison input
|
||||
- keep diagnostics out of the durable cache artifact
|
||||
- sink general walk diagnostics into the normal asset/runtime diagnostics surface
|
||||
- preserve file-scoped diagnostics as segregated walk output for UI consumers
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no remote/shared cache
|
||||
- no final `build`/`pack` incremental pipeline
|
||||
- no background watch service or external reconcile loop
|
||||
- no silent reuse of stale cache entries when file identity no longer matches the current asset file
|
||||
- no cache file per asset root; the baseline artifact remains the workspace-level `assets/.prometeu/cache.json`
|
||||
- no UI contract that exposes raw cache internals directly to Studio
|
||||
- no cache support for unregistered assets; registration remains the prerequisite for internal file analysis and durable cache ownership
|
||||
|
||||
## Execution Shape
|
||||
|
||||
`PR-24` should be treated as an umbrella execution plan, not as one direct implementation PR.
|
||||
|
||||
This work should be split into smaller follow-up PRs so cache persistence, walker reuse policy, and runtime snapshot integration can each land with narrow tests and isolated regressions.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce a packer-owned cache repository around `PackerWorkspacePaths.cachePath(project)`.
|
||||
The repository must load, validate, and save one workspace cache artifact without leaking raw filesystem JSON handling into loaders or walkers.
|
||||
|
||||
2. Define a versioned durable cache model.
|
||||
The baseline model should include:
|
||||
- workspace-level schema/version fields
|
||||
- asset-scoped entries keyed by stable `asset_id`
|
||||
- file-scoped entries keyed by normalized relative path inside the asset root
|
||||
- reusable file facts such as mime type, size, `lastModified`, content fingerprint, and family-specific probe metadata
|
||||
- no persisted diagnostics; diagnostics remain runtime results produced by the current walk only
|
||||
|
||||
3. Extend walker inputs so previous cache is available during content probing.
|
||||
The walker contract should receive the prior asset cache view together with the declaration and asset root, rather than forcing each concrete walker to reopen cache storage on its own.
|
||||
Unregistered assets do not enter this flow; they must be registered first before internal file analysis and cache ownership apply.
|
||||
|
||||
4. Define cache comparison rules inside the walker layer.
|
||||
Baseline rules:
|
||||
- if current file `size` differs from cached `size`, cached data is invalid immediately
|
||||
- if current file `lastModified` is after cached `lastModified`, cached data is invalid immediately
|
||||
- content hash or fingerprint should be the last comparison step, used only when the cheaper checks do not already force invalidation and the policy still needs stronger confirmation
|
||||
- if prior file facts remain valid under that ordered comparison policy, the walker may reuse prior metadata instead of recomputing everything
|
||||
- if identity facts differ, the walker must treat the file as changed and emit fresh probe output
|
||||
- missing prior cache is a normal cache miss, not an error
|
||||
- corrupted or incompatible prior cache should surface diagnostics or operational logging as appropriate, then fall back to a cold walk
|
||||
|
||||
5. Promote `walkResult` from transient scan output to cache refresh input.
|
||||
After a successful walk, the loader must convert only the cacheable portions of the current `walkResult` into the next durable asset cache entry set and merge it into the workspace cache model.
|
||||
Persisted cache data must be limited to reusable probe facts and metadata, never diagnostics.
|
||||
|
||||
6. Attach walk output to the runtime snapshot.
|
||||
The runtime snapshot should retain a dedicated runtime projection of the current walk output, not the raw probe objects themselves, so query services and Studio-facing adapters can access file-scoped probe metadata and file-scoped diagnostics without forcing a new filesystem walk.
|
||||
The initial runtime posture should keep the full available file set and the subset that is currently build-eligible, plus bank-size measurement data needed by future fixed-size hardware bank checks.
|
||||
The raw probe may still carry file bytes during the active walk, but the snapshot projection must strip byte payloads before retention.
|
||||
The snapshot should keep inventory, probe metadata, build-candidate classification, and bank-size measurements, but not whole file contents or raw `PackerFileProbe` instances by default.
|
||||
Later cleanup may reduce that retained surface, but the first implementation should prefer preserving available walk data rather than prematurely trimming it.
|
||||
|
||||
7. Split diagnostic sinks intentionally.
|
||||
Baseline rule:
|
||||
- asset-level or walk-level diagnostics that represent the normal operational truth of the asset should flow into the usual runtime/query diagnostics sink
|
||||
- file-scoped diagnostics produced by probe processing should remain segregated per file inside the walk result projection
|
||||
- Studio may consume those file-scoped diagnostics for detailed UI rendering, but that segregation must not be lost by collapsing everything into one flat diagnostics list
|
||||
- none of those diagnostics are persisted in `cache.json`
|
||||
|
||||
8. Persist cache only at stable visibility points.
|
||||
The normal runtime path should save refreshed cache after the loader finishes building a coherent snapshot.
|
||||
Write-path flows that patch one asset in memory should update only the affected asset cache entry after durable commit and successful re-walk.
|
||||
|
||||
9. Keep runtime snapshot and cache ownership aligned.
|
||||
Runtime snapshot data may retain the current walk output needed by query services, but the durable cache artifact remains a packer-owned operational store under `assets/.prometeu/cache.json`.
|
||||
|
||||
10. Emit observability only at meaningful boundaries.
|
||||
The implementation may emit `cache_hit` and `cache_miss` events or counters, but adapters must not collapse cache behavior into fake asset-change semantics.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- runtime load attempts to read `assets/.prometeu/cache.json` before walking assets
|
||||
- prior asset-scoped cache entries are passed into walkers as comparison input
|
||||
- cache entries are keyed by stable `asset_id`, not by asset path
|
||||
- unregistered assets do not receive cache entries and do not undergo internal file analysis before registration
|
||||
- walkers compare current files against prior facts using ordered checks where `size` invalidates first, `lastModified` invalidates next when the current value is newer, and fingerprint/hash remains the final expensive check
|
||||
- the current walk output is attached to the in-memory runtime snapshot through a byte-free runtime projection, not through raw probe objects
|
||||
- the runtime snapshot keeps enough walk data to expose available files, build-candidate files, and bank-size measurement data
|
||||
- the runtime snapshot does not retain raw bytes for every discovered file by default
|
||||
- normal asset/runtime diagnostics include the general walk diagnostics that should participate in the standard diagnostics surface
|
||||
- file-scoped diagnostics remain segregated in the walk result projection for UI consumers
|
||||
- the resulting `walkResult` is used to refresh the durable cache state
|
||||
- successful runtime load writes a coherent updated cache artifact back to `assets/.prometeu/cache.json`
|
||||
- missing, corrupted, or version-mismatched cache does not block snapshot load; the packer falls back to a cold walk
|
||||
- point write flows that already patch one asset in memory can refresh only that asset's cache slice after commit instead of forcing full cache rebuild
|
||||
- cache entries are isolated by asset and file path so one asset cannot accidentally reuse another asset's file facts
|
||||
- persisted cache does not contain diagnostics from prior runs
|
||||
- Studio list/details behavior remains stable and does not depend on direct cache awareness
|
||||
|
||||
## Tests
|
||||
|
||||
- loader tests for cold load when `cache.json` is absent
|
||||
- loader tests for warm load when prior cache exists and matches current files
|
||||
- loader tests for fallback when `cache.json` is malformed, unreadable, or schema-incompatible
|
||||
- cache model tests proving asset cache lookup is aligned by `asset_id`
|
||||
- walker tests proving changed `size` invalidates reuse immediately
|
||||
- walker tests proving newer `lastModified` invalidates reuse immediately
|
||||
- walker tests proving fingerprint/hash is evaluated only as the last comparison step when cheaper checks do not already invalidate reuse
|
||||
- walker tests proving stable files can reuse prior metadata without changing query-visible results
|
||||
- cache serialization tests proving diagnostics are never written to `cache.json`
|
||||
- snapshot/query tests proving `walkResult` is attached to the runtime asset model
|
||||
- tests proving general walk diagnostics sink into the normal diagnostics surface
|
||||
- tests proving file-scoped diagnostics remain segregated per file for UI-facing consumers
|
||||
- runtime registry tests for point cache refresh after write commit on one asset
|
||||
- event or observability tests for `cache_hit` and `cache_miss` boundaries if those signals are emitted in this wave
|
||||
|
||||
## Risks and Recovery
|
||||
|
||||
- path-keyed cache would become unsafe during relocate flows, so the cache owner key must remain `asset_id`
|
||||
- overly aggressive cache reuse can hide real content changes if comparison rules are under-specified
|
||||
- saving cache at the wrong lifecycle point can publish partial truth that no coherent snapshot ever observed
|
||||
- if one part of the cache flow proves unstable, recovery should disable cache hydration or persistence for that path and preserve the current cold-walk behavior until the narrower follow-up PR is corrected
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/pull-requests/**`
|
||||
- `docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`
|
||||
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/PackerWorkspacePaths.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**`
|
||||
|
||||
## Suggested Next Step
|
||||
|
||||
Derive smaller implementation PRs from `PR-24`:
|
||||
|
||||
1. cache model and repository
|
||||
Scope:
|
||||
- durable `cache.json` schema
|
||||
- load/save repository
|
||||
- `asset_id`-aligned cache lookup
|
||||
- serialization tests proving diagnostics are excluded
|
||||
|
||||
2. walker contract and comparison policy
|
||||
Scope:
|
||||
- previous-cache input contract
|
||||
- ordered invalidation checks by `size`, then newer `lastModified`, then fingerprint/hash
|
||||
- file-scoped diagnostics preservation
|
||||
|
||||
3. runtime snapshot and loader integration
|
||||
Scope:
|
||||
- attach `walkResult` to runtime snapshot
|
||||
- sink general diagnostics into the normal asset/runtime diagnostics surface
|
||||
- refresh cache from the cacheable parts of `walkResult`
|
||||
- point write-path refresh for one affected asset
|
||||
@ -1,76 +0,0 @@
|
||||
# PR-25 Asset Cache Model and Repository
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
`PR-24` defines the need for a durable asset file cache in `assets/.prometeu/cache.json`, but the first executable slice should stop at cache persistence itself.
|
||||
|
||||
Before walkers or runtime snapshot integration can reuse prior file facts safely, the packer needs a stable cache schema, explicit load/save ownership, and tests that prove the cache is keyed correctly and excludes non-cacheable data.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the durable `cache.json` model and repository, keyed by stable `asset_id`, with no persisted diagnostics.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
|
||||
- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
|
||||
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- define the durable schema for `assets/.prometeu/cache.json`
|
||||
- key asset cache ownership by stable `asset_id`
|
||||
- omit unregistered assets from durable cache ownership entirely
|
||||
- key file cache entries by normalized relative path inside the asset root
|
||||
- persist reusable probe facts only:
|
||||
- `mimeType`
|
||||
- `size`
|
||||
- `lastModified`
|
||||
- fingerprint/hash
|
||||
- family-specific metadata
|
||||
- exclude diagnostics from the durable cache artifact
|
||||
- add a packer-owned repository for cache load/save and schema validation
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no walker contract changes yet
|
||||
- no cache comparison or reuse policy yet
|
||||
- no runtime snapshot model changes yet
|
||||
- no Studio adapter changes
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add cache model types under the packer runtime model layer.
|
||||
2. Define one versioned workspace cache artifact for `assets/.prometeu/cache.json`.
|
||||
3. Encode asset entries by `asset_id`, never by asset root path.
|
||||
4. Encode file entries by normalized asset-relative path.
|
||||
5. Add repository load/save behavior with safe fallback on missing or invalid cache files.
|
||||
6. Prove by tests that diagnostics cannot be serialized into the durable cache artifact.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the packer has explicit model types for the durable cache artifact
|
||||
- cache ownership is keyed by `asset_id`
|
||||
- unregistered assets do not receive durable cache entries
|
||||
- file cache entries are keyed by normalized relative file path
|
||||
- repository load on absent cache returns a safe empty state
|
||||
- malformed or schema-incompatible cache can be rejected cleanly without crashing the runtime load path
|
||||
- diagnostics are not part of the serialized cache schema
|
||||
|
||||
## Validation
|
||||
|
||||
- schema serialization tests for workspace cache
|
||||
- repository round-trip tests for valid cache content
|
||||
- repository tests for absent cache file
|
||||
- repository tests for malformed cache file
|
||||
- cache model tests proving `asset_id`-aligned lookup
|
||||
- serialization tests proving diagnostics are excluded from `cache.json`
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/pull-requests/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**`
|
||||
@ -1,71 +0,0 @@
|
||||
# PR-26 Walker Cache Input and Comparison Policy
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Once the durable cache model exists, the next narrow step is to let walkers consume prior cached file facts without coupling them to cache storage.
|
||||
|
||||
This PR defines the cache-aware walker contract and the ordered invalidation policy that decides when prior metadata can be reused and when a fresh probe is mandatory.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver walker-side prior-cache input and a deterministic comparison policy ordered by `size`, then newer `lastModified`, then fingerprint/hash.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
|
||||
- [`./PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- extend walker inputs so they receive prior asset cache state
|
||||
- keep walkers independent from cache repository I/O
|
||||
- apply walker-side internal file analysis only to already-registered assets
|
||||
- define ordered invalidation checks:
|
||||
- changed `size` invalidates immediately
|
||||
- newer `lastModified` invalidates immediately
|
||||
- fingerprint/hash is evaluated last when stronger confirmation is still needed
|
||||
- allow walkers to reuse prior metadata when cached facts remain valid
|
||||
- preserve file-scoped diagnostics in walk output
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no runtime snapshot attachment yet
|
||||
- no cache persistence integration in the loader yet
|
||||
- no point write-path refresh yet
|
||||
- no Studio UI contract changes
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update walker contracts to accept prior asset cache input together with asset root and declaration.
|
||||
2. Keep cache lookup outside concrete walkers; they should receive an already-resolved asset cache view.
|
||||
3. Implement the ordered invalidation policy in the shared walker path.
|
||||
4. Reuse prior metadata only when the ordered checks keep the cached entry valid.
|
||||
5. Preserve file-scoped diagnostics in the resulting walk output for later runtime and UI consumption.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- walkers receive prior asset cache entries as input
|
||||
- the walker layer does not perform cache repository I/O directly
|
||||
- unregistered assets are excluded from internal file analysis and cache-aware walker reuse
|
||||
- changed `size` invalidates prior reuse immediately
|
||||
- newer `lastModified` invalidates prior reuse immediately
|
||||
- fingerprint/hash remains the final expensive comparison step
|
||||
- stable files may reuse prior metadata without changing query-visible semantics
|
||||
- file-scoped diagnostics remain segregated in walk output
|
||||
|
||||
## Validation
|
||||
|
||||
- walker tests proving changed `size` invalidates reuse
|
||||
- walker tests proving newer `lastModified` invalidates reuse
|
||||
- walker tests proving fingerprint/hash is only evaluated after cheaper checks do not already invalidate reuse
|
||||
- walker tests proving stable files can reuse prior metadata
|
||||
- tests proving file-scoped diagnostics remain attached to per-file walk output
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/pull-requests/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**`
|
||||
@ -1,88 +0,0 @@
|
||||
# PR-27 Runtime WalkResult and Cache Integration
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
With cache persistence and walker reuse policy isolated, the final slice is to connect them to the runtime model.
|
||||
|
||||
This PR makes the runtime loader hydrate prior cache before the walk, attach the current `walkResult` to the in-memory snapshot, sink general diagnostics into the normal diagnostics surface, preserve file-scoped diagnostics for UI consumers, and refresh the durable cache from the cacheable portions of the current walk.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver runtime-side integration of prior cache hydration, `walkResult` snapshot attachment, diagnostics sink split, and refreshed cache persistence.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
|
||||
- [`./PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md)
|
||||
- [`./PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md)
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
|
||||
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- load prior `cache.json` during runtime snapshot bootstrap and refresh
|
||||
- resolve prior cache by `asset_id` before invoking the walker
|
||||
- attach a byte-free runtime projection of the current `walkResult` to the in-memory runtime asset model
|
||||
- retain enough walk data in the runtime snapshot to inspect available files, build-candidate files, and bank-size measurement data
|
||||
- avoid retaining raw file bytes for the full discovered file set in the runtime snapshot
|
||||
- sink general walk diagnostics into the normal asset/runtime diagnostics surface
|
||||
- preserve file-scoped diagnostics as segregated walk output for UI consumers
|
||||
- refresh and persist cache from the cacheable portions of the current walk
|
||||
- support point cache refresh for one affected asset after successful write commit and re-walk
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no new Studio feature surface beyond exposing already-owned file-scoped walk data
|
||||
- no background reconcile observer
|
||||
- no build/incremental pipeline work
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Load prior workspace cache at runtime bootstrap and on refresh.
|
||||
2. Resolve the current asset cache slice by `asset_id` and pass it into the walker.
|
||||
Assets without `asset_id` are outside this flow and should not receive internal file analysis or cache ownership.
|
||||
3. Attach a dedicated runtime projection of the current `walkResult` to the runtime snapshot model.
|
||||
The first implementation should keep the available file set, the build-candidate subset, and bank-size measurement data accessible from the snapshot instead of optimizing that shape away early.
|
||||
The runtime projection should drop raw file bytes and should not retain raw `PackerFileProbe` objects unless a narrower later use case proves they are needed.
|
||||
4. Route general walk diagnostics into the standard asset/runtime diagnostics sink.
|
||||
5. Preserve file-scoped diagnostics inside the walk result projection used by later query/UI consumers.
|
||||
6. Persist refreshed cache after coherent runtime load completes.
|
||||
7. Reuse the same logic to refresh one asset cache slice after successful point write commit and re-walk.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- runtime load reads prior cache before invoking walkers
|
||||
- cache lookup passed to the walker is aligned by `asset_id`
|
||||
- assets without `asset_id` are excluded from cache ownership and internal file analysis
|
||||
- runtime assets retain a byte-free projection of the current walk output in memory
|
||||
- runtime assets retain enough walk data to inspect available files, build-candidate files, and bank-size measurement data
|
||||
- runtime snapshot retention excludes raw file bytes for the general discovered file set
|
||||
- general walk diagnostics appear in the normal diagnostics surface
|
||||
- file-scoped diagnostics remain segregated for detailed consumers
|
||||
- refreshed cache written after runtime load contains only cacheable probe facts and metadata
|
||||
- point write flows can refresh only one affected asset cache entry after commit
|
||||
- missing, malformed, or incompatible cache falls back to cold walk without blocking runtime queries
|
||||
|
||||
## Validation
|
||||
|
||||
- loader tests for cold load without cache
|
||||
- loader tests for warm load with cache hydration
|
||||
- snapshot/query tests proving `walkResult` is attached to runtime assets
|
||||
- diagnostics tests proving general sink aggregation and file-scoped segregation
|
||||
- cache refresh tests proving the durable artifact is rebuilt from cacheable walk data only
|
||||
- runtime registry tests for one-asset cache refresh after point write commit
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/pull-requests/**`
|
||||
- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-studio/**` query adapter coverage when file-scoped diagnostics become consumable
|
||||
@ -1,107 +0,0 @@
|
||||
# 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/**`
|
||||
@ -1,93 +0,0 @@
|
||||
# PR-29 Pack Wizard Contract Adjustments for Summary and Validation
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The first public contract wave for the `Pack Wizard` has already landed in `prometeu-packer-api`, but the newly accepted packer decision for `summary` and `validation` closes a more specific shape than the initial API slice.
|
||||
|
||||
In particular:
|
||||
|
||||
- `summary` is no longer aggregate-only;
|
||||
- `summary` must expose a per-asset list for the active pack set;
|
||||
- `validation` is primarily a per-asset blocking-diagnostics list;
|
||||
- `validation` ordering is not a packer concern in the first wave;
|
||||
- aggregate validation data is secondary, not the center of the contract.
|
||||
|
||||
This PR adjusts the public contracts so they match the accepted packer decision exactly.
|
||||
|
||||
Reference decision:
|
||||
|
||||
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Align the public `prometeu-packer-api` contract for `summary` and `validation` with the accepted decision before deeper implementation work continues.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
||||
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
|
||||
- cross-domain reference:
|
||||
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- adjust the public summary DTOs to include:
|
||||
- aggregate included asset count
|
||||
- per-asset summary list
|
||||
- adjust the public validation DTOs to make the per-asset blocking-diagnostics list the primary payload
|
||||
- add or rename DTOs as needed for:
|
||||
- per-asset summary entry
|
||||
- per-asset validation entry
|
||||
- keep `lastModified` present in both summary and validation item contracts
|
||||
- preserve the `read-only` and `non-mutating` nature of summary and validation
|
||||
- keep the Studio-facing API explicit and aligned with the accepted packer decision
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no runtime implementation of summary in `prometeu-packer-v1`
|
||||
- no runtime implementation of validation in `prometeu-packer-v1`
|
||||
- no `pack execution` contract changes unless strictly required by compile compatibility
|
||||
- no Studio implementation work in this PR
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Revisit the current `summary` and `validation` public DTOs in `prometeu-packer-api`.
|
||||
2. Expand the summary result shape so it carries:
|
||||
- total included asset count
|
||||
- per-asset summary entries
|
||||
3. Expand or reshape validation so the returned per-asset entries expose:
|
||||
- asset id
|
||||
- asset name
|
||||
- asset path
|
||||
- `lastModified`
|
||||
- blocking diagnostics
|
||||
4. Keep validation aggregate data optional or secondary rather than the primary response focus.
|
||||
5. Preserve defensive-copy and validation patterns already used by public API records.
|
||||
6. Update Studio compile surfaces only as needed to keep the workspace consuming the revised contracts coherently.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the public summary contract matches the accepted decision shape
|
||||
- the public validation contract matches the accepted decision shape
|
||||
- `lastModified` exists in both per-asset summary and per-asset validation entries
|
||||
- validation payloads carry blocking diagnostics only in the first wave
|
||||
- compile succeeds across `prometeu-packer-api`, `prometeu-packer-v1`, and any directly affected Studio call sites
|
||||
|
||||
## Validation
|
||||
|
||||
- compile validation for `prometeu-packer-api`
|
||||
- compile validation for `prometeu-packer-v1`
|
||||
- compile validation for `prometeu-studio`
|
||||
- lightweight API tests if public message-shape tests already exist
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/decisions/**`
|
||||
- `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/**`
|
||||
- `prometeu-studio/**` compile-level consumers of the summary/validation contracts
|
||||
@ -1,83 +0,0 @@
|
||||
# PR-30 Pack Wizard Summary Snapshot Query
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
With the public contracts aligned, the next step is to actually produce the pack-wizard `summary` from the packer runtime snapshot.
|
||||
|
||||
This is intentionally narrower than full pack execution.
|
||||
The goal is to expose a fast preflight summary of the active pack set so the Studio wizard can open on packer-owned state instead of local UI heuristics.
|
||||
|
||||
Reference decision:
|
||||
|
||||
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Implement snapshot-backed `summary` for the pack wizard over the current `registered + included in build` set.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
|
||||
- cross-domain reference:
|
||||
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement `getPackWorkspaceSummary(...)` in `prometeu-packer-v1`
|
||||
- resolve the active pack set from the runtime snapshot:
|
||||
`registered + included in build`
|
||||
- produce the aggregate included asset count
|
||||
- produce the per-asset summary list with:
|
||||
- asset id
|
||||
- asset name
|
||||
- asset family
|
||||
- min artifact count
|
||||
- max artifact count
|
||||
- `lastModified`
|
||||
- allow `lastModified = 0` in the first wave where the real value is not yet available
|
||||
- keep the query fast and snapshot-backed
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no validation logic in this PR
|
||||
- no pack execution logic in this PR
|
||||
- no emitted-artifact preview in summary
|
||||
- no inclusion of unregistered or excluded assets as explicit summary items
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Resolve the active runtime snapshot for the requested project.
|
||||
2. Filter the snapshot to the active pack set:
|
||||
registered assets included in build.
|
||||
3. Derive one aggregate count from that filtered set.
|
||||
4. Map each included asset into the public per-asset summary DTO.
|
||||
5. Populate `minArtifactCount` and `maxArtifactCount` from the best currently available packer-owned summary facts.
|
||||
6. Populate `lastModified` from packer-owned runtime or filesystem facts when available, otherwise `0`.
|
||||
7. Return the summary result without performing deep validation or artifact planning.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `getPackWorkspaceSummary(...)` returns successfully from snapshot-backed state
|
||||
- the returned set contains only `registered + included in build` assets
|
||||
- the aggregate count matches the per-asset list size
|
||||
- per-asset summary entries expose the fields required by the accepted decision
|
||||
- the operation behaves as a fast read query rather than a deep recomputation path
|
||||
|
||||
## Validation
|
||||
|
||||
- packer unit tests for pack-set filtering
|
||||
- packer unit tests for summary DTO mapping
|
||||
- regression tests proving excluded and unregistered assets do not appear as summary items
|
||||
- Studio smoke validation proving the wizard summary can render from packer-owned data
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-studio/**` wizard summary consumer surfaces if compile adaptation is needed
|
||||
@ -1,91 +0,0 @@
|
||||
# PR-31 Pack Wizard Validation Snapshot Gate
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The `Pack Wizard` validation phase is not a generic workspace scan.
|
||||
It is a pack-set-specific gate over the current `registered + included in build` snapshot state.
|
||||
|
||||
The accepted decision closes the first-wave semantics:
|
||||
|
||||
- validation is read-only and snapshot-backed;
|
||||
- validation looks only at the active pack set;
|
||||
- only `blocking` diagnostics fail validation;
|
||||
- the primary payload is the per-asset blocking-diagnostics list.
|
||||
|
||||
This PR implements that gate in `prometeu-packer-v1`.
|
||||
|
||||
Reference decision:
|
||||
|
||||
- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Implement snapshot-backed pack validation that returns per-asset blocking diagnostics for the active pack set and decides whether packing may proceed.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
|
||||
- [`./PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md)
|
||||
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
- cross-domain reference:
|
||||
[`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement `validatePackWorkspace(...)` in `prometeu-packer-v1`
|
||||
- evaluate only the current `registered + included in build` set from the runtime snapshot
|
||||
- collect only `blocking` diagnostics for the first-wave validation payload
|
||||
- return per-asset validation entries with:
|
||||
- asset id
|
||||
- asset name
|
||||
- asset path
|
||||
- `lastModified`
|
||||
- blocking diagnostics
|
||||
- make validation green when no blocking diagnostics are returned
|
||||
- make validation red when any blocking diagnostics are returned
|
||||
- keep aggregate validation data secondary to the per-asset list
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no pack execution in this PR
|
||||
- no non-blocking diagnostics in the first-wave validation payload
|
||||
- no packer-owned ordering contract for the returned validation list
|
||||
- no deep-sync orchestration in this PR beyond using the current snapshot boundary
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Resolve the current runtime snapshot for the requested project.
|
||||
2. Filter it to the active pack set:
|
||||
`registered + included in build`.
|
||||
3. Gather diagnostics relevant to each asset in that set.
|
||||
4. Keep only diagnostics marked `blocking` for the first-wave validation response.
|
||||
5. Map each asset with blockers into the public per-asset validation DTO.
|
||||
6. Allow `lastModified = 0` temporarily where the real value is not yet available.
|
||||
7. Return validation as green when the per-asset blocker list is empty and red otherwise.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `validatePackWorkspace(...)` evaluates only the active pack set
|
||||
- only blocking diagnostics appear in the first-wave validation payload
|
||||
- validation succeeds when no blocking diagnostics are present
|
||||
- validation fails when any blocking diagnostics are present
|
||||
- per-asset validation entries expose the fields required by the accepted decision
|
||||
- Studio can stop before `Packing` using packer-owned validation alone
|
||||
|
||||
## Validation
|
||||
|
||||
- packer unit tests for pack-set filtering during validation
|
||||
- packer unit tests proving non-blocking diagnostics do not fail the first-wave validation
|
||||
- packer unit tests proving blocking diagnostics do fail validation
|
||||
- DTO-mapping tests for per-asset validation entries
|
||||
- Studio smoke validation proving the wizard blocks on returned blockers
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**`
|
||||
- `prometeu-studio/**` validation consumer surfaces if compile adaptation is needed
|
||||
@ -1,113 +0,0 @@
|
||||
# PR-32 Palette Declarations with Explicit Index Contract
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`, `../runtime`
|
||||
|
||||
## Briefing
|
||||
|
||||
The current authoring shape for `asset.json.output.pipeline.palettes` is still too dependent on list order as semantic identity.
|
||||
|
||||
That is fragile:
|
||||
|
||||
- editorial reordering can silently change meaning;
|
||||
- merges become harder to review safely;
|
||||
- the packer has to infer identity from position instead of reading it explicitly.
|
||||
|
||||
The repository already depends on stable palette ordering for `tile bank` packing.
|
||||
That ordering should therefore be explicit in the authoring contract.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- ongoing agenda:
|
||||
[`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Replace list-position-defined palette identity with an explicit index-bearing declaration contract for `asset.json.output.pipeline.palettes`.
|
||||
|
||||
Recommended shape:
|
||||
|
||||
```json
|
||||
"palettes": [
|
||||
{
|
||||
"index": 0,
|
||||
"palette": { ... }
|
||||
},
|
||||
{
|
||||
"index": 1,
|
||||
"palette": { ... }
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- tile-bank materialization agenda in `docs/packer/agendas`
|
||||
- runtime-side tile-bank consumer contract already aligned around stable palette ids
|
||||
|
||||
## Scope
|
||||
|
||||
- define the normative authoring shape for `output.pipeline.palettes`
|
||||
- make `index` the semantic identity of each declared palette
|
||||
- require packer normalization to sort by `index`, not by list position
|
||||
- define diagnostics for duplicate, missing, invalid, or malformed palette entries
|
||||
- prepare propagation into:
|
||||
- packer specs
|
||||
- parser/runtime-facing normalization code
|
||||
- Studio editing surfaces if they expose palette management
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no immediate migration of `artifacts` in this PR
|
||||
- no tile-bank payload implementation in this PR
|
||||
- no runtime code changes in this PR
|
||||
- no speculative keyed-object JSON contract for palettes in this wave
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update the packer-side documentation/decision chain to make palette identity explicit.
|
||||
2. Define `output.pipeline.palettes` as a list of records with:
|
||||
- `index`
|
||||
- `palette`
|
||||
3. State that semantic ordering is ascending numeric `index`, never raw list position.
|
||||
4. Define structural diagnostics:
|
||||
- duplicate `index` => blocking
|
||||
- negative or malformed `index` => blocking
|
||||
- missing `palette` payload => blocking
|
||||
- palette count above the runtime-facing v1 limit => blocking
|
||||
5. Define whether index gaps are:
|
||||
- blocking
|
||||
- or warning/advisory
|
||||
6. Prepare follow-up implementation PRs for parser, validation, and Studio surfaces.
|
||||
|
||||
## Contract Direction
|
||||
|
||||
First-wave packer contract direction:
|
||||
|
||||
1. `output.pipeline.palettes` remains a JSON array for authoring ergonomics;
|
||||
2. each entry must declare an explicit `index`;
|
||||
3. each entry must declare a `palette` object payload;
|
||||
4. packer meaning comes from numeric `index`, not from the physical array position;
|
||||
5. the runtime-facing `palette_id` consumed later by tile/sprite draw paths is the normalized numeric palette `index`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the packer docs/spec path no longer relies on raw list order as palette identity
|
||||
- the explicit-index palette shape is documented clearly enough for parser and Studio implementation
|
||||
- duplicate or malformed palette indices are identified as structural diagnostics
|
||||
- the contract leaves no ambiguity about whether sorting happens by array order or by `index`
|
||||
|
||||
## Validation
|
||||
|
||||
- editorial validation across packer agenda/decision/spec material
|
||||
- parser-oriented review proving the contract is implementable without hidden heuristics
|
||||
- Studio-facing review confirming the editing UX can preserve stable palette identity
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/agendas/**`
|
||||
- `docs/packer/decisions/**`
|
||||
- `docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
||||
- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
- future parser/runtime materialization code under `prometeu-packer-v1`
|
||||
@ -1,80 +0,0 @@
|
||||
# PR-33 Tile Bank Spec Propagation and Runtime Contract Alignment
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `../runtime`, `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The `Tile Bank Packing Materialization Decision` is now closed.
|
||||
|
||||
Before more code lands, the normative spec path needs to be updated so implementation is not forced to infer format details from agendas and decisions.
|
||||
|
||||
This PR is editorial-first.
|
||||
Its job is to propagate the accepted tile-bank producer contract into the relevant packer specs and to make the runtime alignment explicit.
|
||||
|
||||
## Objective
|
||||
|
||||
Update the normative spec corpus so `tile bank` v1 packing has one unambiguous producer contract.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
|
||||
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
|
||||
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- propagate the accepted `tile bank` v1 contract into packer specs
|
||||
- define canonical payload semantics for `TILES/indexed_v1`
|
||||
- define metadata convergence shape for tile-bank runtime entries
|
||||
- make runtime-aligned size and decoded-size formulas explicit
|
||||
- document the fixed `256 x 256` target and row-major slot semantics
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no production code changes
|
||||
- no walker refactor
|
||||
- no payload emitter implementation
|
||||
- no runtime implementation work
|
||||
|
||||
## Method
|
||||
|
||||
1. Update [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md).
|
||||
2. Define `TILES/indexed_v1` producer semantics explicitly:
|
||||
- `1 artifact = 1 tile`
|
||||
- `tile_id = normalized artifacts[*].index`
|
||||
- fixed `256 x 256` emitted sheet
|
||||
- row-major placement
|
||||
- packed `u4` pixel plane
|
||||
- `64 * 16 * u16` RGB565 palette block
|
||||
3. Document runtime entry derivation:
|
||||
- `bank_type = TILES`
|
||||
- `codec = NONE`
|
||||
- `size = ceil(width * height / 2) + 2048`
|
||||
- `decoded_size = (width * height) + 2048`
|
||||
4. Document metadata normalization:
|
||||
- `output.metadata -> metadata`
|
||||
- `output.codec_configuration -> metadata.codec`
|
||||
- `output.pipeline -> metadata.pipeline`
|
||||
5. Cross-reference the runtime-side metadata normalization discussion without pretending it is already closed there.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the packer spec corpus contains one explicit producer contract for tile-bank v1
|
||||
- the payload shape no longer needs to be reconstructed from agenda text
|
||||
- size, decoded-size, palette count, and metadata shape are all normative
|
||||
- the spec states what the producer emits because that is what the consumer requires
|
||||
|
||||
## Validation
|
||||
|
||||
- editorial review against the accepted decision
|
||||
- consistency check against runtime specs and loader assumptions
|
||||
- terminology review for `tile_id`, `palette_id`, `size`, `decoded_size`, and metadata segmentation
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
- possibly `docs/packer/specs/1. Domain and Artifact Boundary Specification.md`
|
||||
- possibly `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
|
||||
@ -1,75 +0,0 @@
|
||||
# PR-34 Tile Bank Diagnostics and Validation Hardening
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The tile-bank decision closed the structural blockers and warnings that must exist before pack emission.
|
||||
|
||||
Those diagnostics belong in the walker/materialization path so they surface during validation and are naturally rerun by `packWorkspace(...)` when a fresh frozen snapshot is created.
|
||||
|
||||
This PR isolates that diagnostic work from payload emission.
|
||||
|
||||
## Objective
|
||||
|
||||
Add the accepted tile-bank diagnostics to the packer walk/materialization path and make validation consume them consistently.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
|
||||
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- `PR-33` for normative spec propagation
|
||||
|
||||
## Scope
|
||||
|
||||
- add tile-bank structural blocking diagnostics
|
||||
- add tile-bank warning diagnostics for fragile indices
|
||||
- ensure those diagnostics live in the walker/materialization path
|
||||
- ensure validation consumes them without special late pack-only logic
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no full payload emission yet
|
||||
- no staging/promote pipeline yet
|
||||
- no shipper behavior
|
||||
- no future multi-tile-per-artifact support
|
||||
|
||||
## Method
|
||||
|
||||
1. Add blocking diagnostics for:
|
||||
- duplicate `artifacts[*].index`
|
||||
- gaps in normalized artifact indices
|
||||
- fixed-sheet capacity overflow
|
||||
- banks without declared palettes
|
||||
- palette declaration count above `64`
|
||||
- malformed palette declarations
|
||||
- missing or invalid required tile-bank metadata
|
||||
- failures to normalize artifacts into deterministic tile candidates
|
||||
2. Add `WARNING` diagnostics for fragile tile indices across the full declared bank palette set.
|
||||
3. Ensure diagnostics are attached at file/asset walk time so:
|
||||
- `GetAssetDetails`
|
||||
- `ValidatePackWorkspace`
|
||||
- future pack rerun gate
|
||||
all see the same structural findings.
|
||||
4. Add tests that distinguish blocking failures from advisory warnings.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- validation returns blocked tile-bank assets when any accepted blocker exists
|
||||
- fragile-index findings are visible but do not block by themselves
|
||||
- no tile-bank structural problem is discovered only during final byte emission
|
||||
- the same diagnostic vocabulary is visible in details and validation paths
|
||||
|
||||
## Validation
|
||||
|
||||
- targeted service and walker tests
|
||||
- validation-flow regression tests
|
||||
- asset-details regression tests for warning and blocking surfaces
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer-v1` tile-bank walker/materialization code
|
||||
- `prometeu-packer-v1` validation/query services
|
||||
- related tests under `prometeu-packer-v1/src/test`
|
||||
|
||||
@ -1,69 +0,0 @@
|
||||
# PR-35 Packing-Aware Walkers and Runtime Materialization Preparation
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Pack execution now depends on a frozen in-memory execution snapshot, but the repository deliberately chose not to fork discovery into one runtime walker stack and one packing walker stack.
|
||||
|
||||
This PR prepares the existing walker/materialization path so it can serve both runtime reads and pack execution with explicit policy.
|
||||
|
||||
## Objective
|
||||
|
||||
Prepare walkers and runtime materialization for packing-aware projection without implementing final pack emission yet.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
|
||||
- `PR-34` for diagnostics already present in the walk/materialization path
|
||||
|
||||
## Scope
|
||||
|
||||
- add optional content bytes to runtime walk projection
|
||||
- introduce or finish the accepted materialization config/policy shape
|
||||
- keep family walkers discovery-oriented
|
||||
- enable packing-focused projection filtering over discovered probes
|
||||
- make build-relevant content bytes available for packing snapshots only
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final `packWorkspace(...)` implementation yet
|
||||
- no staging/promotion yet
|
||||
- no tile-bank payload bytes emitted yet
|
||||
- no alternative walker stack
|
||||
|
||||
## Method
|
||||
|
||||
1. Add `Optional<byte[]>` support to `PackerRuntimeWalkFile`.
|
||||
2. Ensure full probes can still carry bytes internally during discovery.
|
||||
3. Materialize runtime projection using explicit config/policy:
|
||||
- runtime mode suppresses optional bytes
|
||||
- packing mode injects optional bytes
|
||||
- projection filter keeps only build-relevant selected probes
|
||||
4. Keep family walkers focused on relevance-by-family.
|
||||
5. Add tests showing:
|
||||
- runtime default projection does not retain bytes
|
||||
- packing projection retains bytes only for relevant selected files
|
||||
- the same discovery path serves both modes
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the repository has one walker discovery path, not two divergent ones
|
||||
- packing projection can freeze build-relevant bytes in memory
|
||||
- runtime-backed reads do not become wasteful full-memory mirrors
|
||||
- selected build inputs survive into runtime walk projection with optional bytes when packing mode is requested
|
||||
|
||||
## Validation
|
||||
|
||||
- targeted runtime materialization tests
|
||||
- walker reuse regression tests
|
||||
- cache integration review where relevant
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer-v1` walker models
|
||||
- `prometeu-packer-v1` runtime materializer/export path
|
||||
- related tests under `prometeu-packer-v1/src/test`
|
||||
|
||||
@ -1,86 +0,0 @@
|
||||
# PR-36 Pack Workspace Execution with Frozen Snapshot and Staging
|
||||
|
||||
Domain Owner: `docs/packer`
|
||||
Cross-Domain Impact: `docs/studio`, `../runtime`
|
||||
|
||||
## Briefing
|
||||
|
||||
After specs, diagnostics, and packing-aware materialization are in place, the remaining step is the actual pack execution pipeline.
|
||||
|
||||
This PR implements `packWorkspace(...)` as the first end-to-end writer that:
|
||||
|
||||
- reruns the gate on a fresh execution snapshot;
|
||||
- materializes build outputs from frozen in-memory inputs;
|
||||
- stages outputs before promotion;
|
||||
- and publishes coherent final artifacts to `build/`.
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the first-wave `packWorkspace(...)` pipeline with frozen snapshot input, tile-bank payload emission, and staged publication.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md)
|
||||
- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md)
|
||||
- `PR-33`
|
||||
- `PR-34`
|
||||
- `PR-35`
|
||||
|
||||
## Scope
|
||||
|
||||
- implement pack rerun gate on a fresh execution snapshot
|
||||
- materialize tile-bank payload bytes from frozen in-memory inputs
|
||||
- emit `assets.pa` and companion outputs in staging
|
||||
- promote staged outputs into final `build/` locations only on coherent success
|
||||
- return structured pack results for blocked, failed, and successful outcomes
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no shipper packaging or `.pbc` generation
|
||||
- no remote or incremental build behavior
|
||||
- no cancellation semantics
|
||||
- no non-tile-bank payload families unless they are already trivial and fully decided
|
||||
|
||||
## Method
|
||||
|
||||
1. Create a fresh frozen execution snapshot for the current included-in-build set.
|
||||
2. Rerun the pack validation gate on that snapshot before byte emission begins.
|
||||
3. For tile banks:
|
||||
- normalize selected artifacts into one row-major `256 x 256` sheet
|
||||
- pack tile pixels as `u4`
|
||||
- emit the `64 * 16 * 2` RGB565 palette block
|
||||
- derive runtime entry metadata using the accepted segmentation contract
|
||||
4. Emit staged outputs under `build/.staging/<operation-id>/`.
|
||||
5. Promote staged outputs into:
|
||||
- `build/assets.pa`
|
||||
- `build/asset_table.json`
|
||||
- `build/preload.json`
|
||||
- `build/asset_table_metadata.json`
|
||||
6. Return structured terminal results that distinguish:
|
||||
- gate failure
|
||||
- execution/materialization failure
|
||||
- persistence/promotion failure
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `packWorkspace(...)` never emits from live filesystem rereads after frozen snapshot creation
|
||||
- gate rerun blocks stale-invalid projects even if validation was green earlier
|
||||
- failed execution before promotion does not leave partial final build outputs visible as success
|
||||
- successful execution publishes coherent final build outputs
|
||||
- tile-bank payload bytes satisfy the accepted producer contract and runtime consumer assumptions
|
||||
|
||||
## Validation
|
||||
|
||||
- targeted `packWorkspace(...)` service tests
|
||||
- tile-bank conformance tests from artifacts to emitted payload
|
||||
- staging/promotion failure-path tests
|
||||
- regression tests for blocked vs failed vs successful results
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-packer-api` pack result contract
|
||||
- `prometeu-packer-v1` pack execution service
|
||||
- `prometeu-packer-v1` tile-bank payload materializer
|
||||
- `prometeu-packer-v1` staging/promote pipeline
|
||||
- related tests under `prometeu-packer-v1/src/test`
|
||||
|
||||
@ -2,6 +2,12 @@
|
||||
|
||||
This directory contains self-contained packer change proposals for review.
|
||||
|
||||
Current retained set:
|
||||
|
||||
- none
|
||||
|
||||
The previous execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/).
|
||||
|
||||
## Purpose
|
||||
|
||||
A pull request document packages a packer change as an executable plan before final integration.
|
||||
@ -58,52 +64,5 @@ A pull request may plan code and spec consequences, but it must not replace a mi
|
||||
|
||||
## Production Sequence
|
||||
|
||||
The current production track for the standalone `prometeu-packer` project is:
|
||||
|
||||
1. [`PR-01-packer-project-bootstrap-and-module-boundaries.md`](./PR-01-packer-project-bootstrap-and-module-boundaries.md)
|
||||
2. [`PR-02-workspace-init-registry-and-identity-foundation.md`](./PR-02-workspace-init-registry-and-identity-foundation.md)
|
||||
3. [`PR-03-asset-declaration-parsing-validation-and-details-contract.md`](./PR-03-asset-declaration-parsing-validation-and-details-contract.md)
|
||||
4. [`PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md)
|
||||
5. [`PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md)
|
||||
6. [`PR-06-doctor-diagnostics-and-safe-fix-baseline.md`](./PR-06-doctor-diagnostics-and-safe-fix-baseline.md)
|
||||
7. [`PR-07-build-plan-determinism-and-cache-key-foundation.md`](./PR-07-build-plan-determinism-and-cache-key-foundation.md)
|
||||
8. [`PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md)
|
||||
9. [`PR-09-event-lane-progress-and-studio-operational-integration.md`](./PR-09-event-lane-progress-and-studio-operational-integration.md)
|
||||
10. [`PR-10-versioning-migration-trust-and-production-gates.md`](./PR-10-versioning-migration-trust-and-production-gates.md)
|
||||
11. [`PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
|
||||
12. [`PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md)
|
||||
13. [`PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md)
|
||||
14. [`PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md)
|
||||
15. [`PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
||||
16. [`PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
|
||||
17. [`PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
|
||||
18. [`PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md)
|
||||
19. [`PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md)
|
||||
20. [`PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md)
|
||||
21. [`PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
|
||||
22. [`PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md`](./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md)
|
||||
23. [`PR-23-move-asset-action-wizard-and-fs-first-relocation.md`](./PR-23-move-asset-action-wizard-and-fs-first-relocation.md)
|
||||
24. [`PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md)
|
||||
25. [`PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md)
|
||||
26. [`PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md)
|
||||
27. [`PR-27-runtime-walkresult-and-cache-integration.md`](./PR-27-runtime-walkresult-and-cache-integration.md)
|
||||
28. [`PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
||||
29. [`PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md)
|
||||
30. [`PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md)
|
||||
31. [`PR-31-pack-wizard-validation-snapshot-gate.md`](./PR-31-pack-wizard-validation-snapshot-gate.md)
|
||||
32. [`PR-32-palette-declarations-with-explicit-index-contract.md`](./PR-32-palette-declarations-with-explicit-index-contract.md)
|
||||
33. [`PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md`](./PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md)
|
||||
34. [`PR-34-tile-bank-diagnostics-and-validation-hardening.md`](./PR-34-tile-bank-diagnostics-and-validation-hardening.md)
|
||||
35. [`PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md`](./PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md)
|
||||
36. [`PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md`](./PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md)
|
||||
|
||||
Current wave discipline from `PR-11` onward:
|
||||
|
||||
- cleanup and active-surface reduction happen before runtime implementation;
|
||||
- the wave is service-first and Studio-driven;
|
||||
- `doctor`, `build/pack`, and background reconcile are explicitly deferred;
|
||||
- code that is not used by the active service wave should be removed instead of preserved speculatively.
|
||||
|
||||
Recommended dependency chain:
|
||||
|
||||
`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18 -> PR-19 -> PR-20 -> PR-21 -> PR-22 -> PR-23 -> PR-24 -> PR-25 -> PR-26 -> PR-27 -> PR-28 -> PR-29 -> PR-30 -> PR-31 -> PR-32 -> PR-33 -> PR-34 -> PR-35 -> PR-36`
|
||||
When a new execution wave starts, add only the PRs that still represent pending work.
|
||||
Do not repopulate this directory with already-absorbed historical implementation slices.
|
||||
|
||||
@ -104,10 +104,15 @@ The preferred Studio documentation flow is:
|
||||
|
||||
- `agendas/` stores currently open Studio questions.
|
||||
- `decisions/` stores only decisions that still need propagation.
|
||||
- `pull-requests/` stores execution plans.
|
||||
- `pull-requests/` stores only execution plans for pending work.
|
||||
- `specs/` stores the normative Studio contract.
|
||||
- `learn/` stores teaching-oriented Studio knowledge.
|
||||
|
||||
The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
|
||||
The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/).
|
||||
At this moment:
|
||||
|
||||
- `agendas/` retains only topics that are still open;
|
||||
- `decisions/` is empty because the last accepted wave was fully propagated;
|
||||
- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`.
|
||||
|
||||
If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`.
|
||||
|
||||
@ -1,80 +0,0 @@
|
||||
# Asset Bank Composition Snapshot Transfer to Details DTOs Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
The `Bank Composition` section needs a stable details-facing data shape before any component or middleware work can proceed.
|
||||
|
||||
Today the underlying information comes from two different sources:
|
||||
|
||||
- snapshot state derived from `walkResult`, which should feed `available` files;
|
||||
- `asset.json`, which should feed the currently `selected` files for build composition.
|
||||
|
||||
This agenda exists to close how those sources should be transferred into Studio-facing DTOs for `Asset Details`.
|
||||
|
||||
## Context
|
||||
|
||||
Recent packer/runtime work already gives the Studio enough source information to populate a first-wave `Bank Composition` section:
|
||||
|
||||
- registered assets have stable identity;
|
||||
- the snapshot already contains file inventory derived from `walkResult`;
|
||||
- blocking diagnostics already exclude files from being generally available;
|
||||
- selection state is persisted in `asset.json` and is expected to move through the newer `artifacts` shape.
|
||||
|
||||
The Studio should not bind raw UI code directly to packer internals.
|
||||
The section needs a dedicated Studio DTO layer.
|
||||
|
||||
## Options
|
||||
|
||||
1. Bind the UI directly to snapshot and manifest shapes.
|
||||
2. Build one dedicated Studio bank-file DTO for both `available` and `selected` rows.
|
||||
3. Build separate DTOs for `available` rows and `selected` rows.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Direct binding is fast initially but couples Studio too tightly to packer/runtime structures.
|
||||
2. One shared DTO keeps the section simpler and is easier to use across transfer list, meter, and staged draft state.
|
||||
3. Separate DTOs may model source differences more explicitly, but they add mapping and coordination overhead early.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Adopt one dedicated Studio DTO family for bank composition rows and section state.
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- `walkResult`-derived snapshot rows become `available`;
|
||||
- `asset.json` composition state becomes `selected`;
|
||||
- both are projected into Studio-owned DTOs before reaching the section UI;
|
||||
- the DTO should be generic enough to work for any bank type, even if family-specific fields arrive later.
|
||||
- the DTO field set should stay intentionally small and grow only when a concrete UI need appears.
|
||||
|
||||
### First-Wave DTO Baseline
|
||||
|
||||
The first-wave DTO direction is intentionally pragmatic:
|
||||
|
||||
- define one Studio-owned bank-file DTO family for both `available` and `selected` rows;
|
||||
- add fields incrementally as real section behavior requires them;
|
||||
- do not project blocking files into the UI DTO layer at all;
|
||||
- keep selected-file order visual in the UI, but persist it in `asset.json` through an explicit index shape such as `{ file, index }`.
|
||||
- start with this minimum first-wave field set:
|
||||
`fileId/path`, `displayName`, `size`, `lastModified`, `fingerprint`, and `metadata`.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. The DTO field set should start small and grow only as concrete UI needs appear.
|
||||
2. Only non-blocking files become `available` DTOs; blocking files should not be projected into the section DTO layer.
|
||||
3. UI ordering is visual, while persisted ordering in `asset.json` should use an explicit index representation such as `{ file, index }`.
|
||||
4. The first DTO revision should start with `fileId/path`, `displayName`, `size`, `lastModified`, `fingerprint`, and `metadata`.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that closes the first-wave Studio DTO shape for `Bank Composition` details data.
|
||||
@ -1,87 +0,0 @@
|
||||
# Asset Bank Composition Base Components Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
The `Bank Composition` section depends on two new Studio components:
|
||||
|
||||
- `StudioDualListView<T>`
|
||||
- `StudioAssetCapacityMeter`
|
||||
|
||||
Those components need a first-wave contract and scope before the section shell or middleware can be implemented safely.
|
||||
|
||||
## Context
|
||||
|
||||
The current direction is already partially fixed:
|
||||
|
||||
- `StudioDualListView<T>` should be abstract;
|
||||
- the first concrete subclass should be asset-details-specific;
|
||||
- right-list ordering must support `move up`, `move down`, and visible indices;
|
||||
- `StudioAssetCapacityMeter` should be a vertical, game-like progress bar with color bands and percentage text;
|
||||
- both components should stay intentionally dumb and leave family-specific rules to middleware/controller logic.
|
||||
|
||||
## Options
|
||||
|
||||
1. Build highly generic reusable components from the start.
|
||||
2. Build bank-composition-scoped Studio components with narrow first-wave APIs.
|
||||
3. Skip dedicated components and build the section directly inside `AssetDetails`.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Highly generic components risk overengineering before the first section is proven.
|
||||
2. Narrow first-wave components keep momentum and preserve room to generalize later from real usage.
|
||||
3. Inline section code would move faster once, but it would bury behavior that already deserves named UI building blocks.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Build dedicated first-wave components with narrow APIs:
|
||||
|
||||
- abstract `StudioDualListView<T>` as the transfer-list base;
|
||||
- one asset-details concrete subclass first;
|
||||
- `StudioAssetCapacityMeter` as a dumb vertical meter component with color thresholds and percentage display.
|
||||
|
||||
Do not force broad reuse rules yet.
|
||||
|
||||
### First-Wave Component Baseline
|
||||
|
||||
The first-wave component contract should stay intentionally small.
|
||||
|
||||
`StudioDualListView<T>` should expose only the hooks needed for the initial bank-composition section:
|
||||
|
||||
- row text and/or row graphic projection;
|
||||
- current left and right collections;
|
||||
- current selection state;
|
||||
- move left-to-right;
|
||||
- move right-to-left;
|
||||
- `moveUp`;
|
||||
- `moveDown`;
|
||||
- visible index refresh for the right-side list.
|
||||
|
||||
The first concrete asset-details subclass should render rows directly.
|
||||
Do not introduce a separate row renderer abstraction yet.
|
||||
|
||||
`StudioAssetCapacityMeter` should start as a dumb visual component with these baseline inputs:
|
||||
|
||||
- `progress` in the `0..1` range;
|
||||
- a label, including percentage text when needed;
|
||||
- a severity band state;
|
||||
- optional hint text.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. `StudioDualListView<T>` should expose only a narrow first-wave hook set for row projection, selection, transfers, reordering, and right-list index refresh.
|
||||
2. The first concrete asset-details subclass should own row rendering directly.
|
||||
3. `StudioAssetCapacityMeter` should start with `progress`, label, severity band state, and optional hint text.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the first-wave component contracts for `StudioDualListView<T>` and `StudioAssetCapacityMeter`.
|
||||
@ -1,77 +0,0 @@
|
||||
# Asset Bank Composition Section Shell Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
`Bank Composition` needs a section shell inside `Asset Details` before behavior is added.
|
||||
|
||||
That shell must align visually and operationally with existing sections, especially `Runtime Contract`, instead of inventing a separate layout and editing model.
|
||||
|
||||
## Context
|
||||
|
||||
The current baseline is already known:
|
||||
|
||||
- `Bank Composition` is a `VBox` section like the others;
|
||||
- it is always visible for the current bank-based families;
|
||||
- it should follow the same staged-editing model as `Runtime Contract`;
|
||||
- the section body should place the dual list on the left and the capacity meter on the right.
|
||||
|
||||
This agenda focuses on the static shell and section composition, not the internal behavior.
|
||||
|
||||
## Options
|
||||
|
||||
1. Add the section only when behavior is ready.
|
||||
2. Build the section shell first, with placeholder or disabled behavior.
|
||||
3. Hide the section behind an experimental flag.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Waiting for full behavior keeps the surface hidden longer and delays visual integration feedback.
|
||||
2. A shell-first approach lets the Studio validate section rhythm, spacing, controls, and staged-edit affordances early.
|
||||
3. A flag adds operational complexity without much value if the section is already part of the near-term plan.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Create the `Bank Composition` section shell early, with no real behavior yet.
|
||||
|
||||
Baseline expectations:
|
||||
|
||||
- section header and actions align with `Runtime Contract`;
|
||||
- `change`, `apply`, `reset`, and `cancel` are part of the shell contract;
|
||||
- body layout already reserves the dual-list and meter regions;
|
||||
- the shell may render with placeholder or disabled internals until middleware arrives.
|
||||
|
||||
### First-Wave Shell Baseline
|
||||
|
||||
The first-wave shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level.
|
||||
|
||||
That includes:
|
||||
|
||||
- the same section rhythm and action placement model;
|
||||
- the same staged-edit shell expectations;
|
||||
- alignment with the existing `FormSession` pattern instead of inventing a separate section lifecycle.
|
||||
|
||||
Before middleware wiring is ready, the body should render in a disabled or read-only state rather than as an empty placeholder.
|
||||
|
||||
Outside `change` mode, the section should show the current persisted state as read-only.
|
||||
It should not stay visually neutral or look absent when data already exists.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. The section shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level.
|
||||
2. The shell should align with the existing `FormSession` model for staged editing.
|
||||
3. Before middleware is ready, the body should render disabled or read-only internals instead of an empty placeholder.
|
||||
4. Outside `change` mode, the section should render the current persisted state as read-only.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the shell contract and static layout of the `Bank Composition` section.
|
||||
@ -1,92 +0,0 @@
|
||||
# Asset Bank Composition Middleware and Staged Editing Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
`StudioDualListView<T>` and `StudioAssetCapacityMeter` are intentionally dumb.
|
||||
That means `Bank Composition` needs a middleware/controller layer that owns:
|
||||
|
||||
- family-specific capacity rules;
|
||||
- staged draft state;
|
||||
- `change` / `apply` / `reset` / `cancel` orchestration;
|
||||
- hard-limit decisions about whether a candidate file can enter the selected list.
|
||||
|
||||
Without that layer, component responsibilities will blur quickly.
|
||||
|
||||
## Context
|
||||
|
||||
The current direction already rejects two extremes:
|
||||
|
||||
- no component should hide bank-family rules internally;
|
||||
- the first wave should not overgeneralize into a universal bank manager abstraction.
|
||||
|
||||
The middleware/controller therefore needs to be explicit, scoped to `Asset Details`, and designed to evolve incrementally.
|
||||
|
||||
## Options
|
||||
|
||||
1. Put orchestration inside the section control itself.
|
||||
2. Create a dedicated bank-composition middleware/controller for the section.
|
||||
3. Push family-specific logic down into the transfer list and meter components.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Section-local orchestration reduces file count initially, but risks turning `AssetDetails` into a heavy behavior host.
|
||||
2. A dedicated middleware/controller keeps the section and components simpler while preserving room for bank-family policies.
|
||||
3. Embedding rules into components breaks the current design goal of keeping them dumb and composable.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Create a dedicated bank-composition middleware/controller for the section.
|
||||
|
||||
Baseline expectations:
|
||||
|
||||
- own the draft state while editing is active;
|
||||
- translate persisted state into editable state on `change`;
|
||||
- support `reset` back to the persisted state;
|
||||
- support `cancel` by discarding draft changes;
|
||||
- keep `apply` stubbed or disabled until persistence is wired;
|
||||
- delegate family-specific capacity logic through narrowly scoped policies instead of premature platform-wide abstractions.
|
||||
|
||||
### First-Wave Middleware Baseline
|
||||
|
||||
The first wave should not introduce a second session model parallel to the one already used by Studio.
|
||||
|
||||
The middleware/controller should be built around `StudioFormSession<BankCompositionDraft>` as the common staged-edit core.
|
||||
|
||||
Family-specific variation should not come from subclassing `StudioFormSession`.
|
||||
It should come from family-specific draft factories and policies that operate on a shared session model.
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- `StudioFormSession<BankCompositionDraft>` owns `source`, `draft`, `mode`, `isDirty`, `beginEdit`, `reset`, `cancel`, and `apply`;
|
||||
- the bank-composition middleware/controller coordinates that form session for the section;
|
||||
- each asset family can offer its own draft-construction and bank-composition policy implementation;
|
||||
- those policies should decide transfer eligibility, reorder effects, capacity usage, and hard-limit blockers;
|
||||
- `apply` may remain stubbed or disabled until persistence is wired, but the session contract should already be complete.
|
||||
|
||||
The minimal state published by the middleware/controller should be one section-facing view model carrying:
|
||||
|
||||
- shell state such as `isEditing`, `isDirty`, and action availability;
|
||||
- left and right list state;
|
||||
- capacity-meter state;
|
||||
- active blockers and hint messages when relevant.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. The middleware/controller should be built around `StudioFormSession<BankCompositionDraft>`, not a parallel staged-edit model.
|
||||
2. Family-specific behavior should come from draft factories and policies, not from subclassing `StudioFormSession`.
|
||||
3. Family-specific rules should be represented first as small policies offered per asset family.
|
||||
4. The middleware/controller should publish one section-facing view model with shell state, list state, meter state, blockers, and hints.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the middleware/controller contract and staged-edit lifecycle for the first wave.
|
||||
@ -1,94 +0,0 @@
|
||||
# Asset Bank Composition WorkspaceBus Interaction Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
The `Bank Composition` section should use `workspaceBus` for coordination, but the first-wave event contract should stay small and be designed together with the middleware/controller.
|
||||
|
||||
This agenda exists to close the first minimal event surface without inventing an oversized bus protocol too early.
|
||||
|
||||
## Context
|
||||
|
||||
The current baseline is already known:
|
||||
|
||||
- events and middleware should evolve together;
|
||||
- the first event baseline can stay very small;
|
||||
- capacity changes are naturally expressed as percentage deltas or level changes in the `0..1` range;
|
||||
- the transfer list and meter should be consumers of orchestrated state, not independent sources of product rules.
|
||||
|
||||
## Options
|
||||
|
||||
1. Define a broad event taxonomy upfront.
|
||||
2. Define only the minimum events needed for the first staged-edit interaction loop.
|
||||
3. Avoid `workspaceBus` and wire components directly.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. A broad taxonomy is easy to regret and hard to prune once code lands.
|
||||
2. A minimal contract matches the current incremental direction and keeps future changes cheap.
|
||||
3. Direct wiring would fight the current workspace architecture and reduce observability of section state changes.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Define a minimal first-wave `workspaceBus` contract together with the middleware/controller.
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- begin with the smallest useful set of section-local events;
|
||||
- include capacity increase/decrease semantics in the `0..1` range only as needed;
|
||||
- avoid encoding family-specific product rules directly into bus event types.
|
||||
|
||||
### First-Wave Event Baseline
|
||||
|
||||
The first wave should keep user actions local to the middleware/controller whenever possible.
|
||||
|
||||
That means the following actions do not need to become public `workspaceBus` commands in the first implementation:
|
||||
|
||||
- `beginEdit`
|
||||
- `moveToSelected`
|
||||
- `moveToAvailable`
|
||||
- `moveUp`
|
||||
- `moveDown`
|
||||
- `reset`
|
||||
- `cancel`
|
||||
- `apply`
|
||||
|
||||
The middleware/controller should receive those actions locally, recalculate section state, and publish only the state transitions or lifecycle notifications that matter outside the section.
|
||||
|
||||
The first public `workspaceBus` notifications should stay minimal:
|
||||
|
||||
- `BankCompositionDraftChanged`
|
||||
- `BankCompositionCapacityChanged`
|
||||
- `BankCompositionApplyRequested`
|
||||
- `BankCompositionApplied`
|
||||
- `BankCompositionApplyFailed`
|
||||
|
||||
Capacity notifications should use absolute progress in the `0..1` range rather than deltas.
|
||||
|
||||
A practical first-wave shape for capacity notifications is:
|
||||
|
||||
- `progress`
|
||||
- `severity`
|
||||
- `blocked`
|
||||
|
||||
If internal increase/decrease semantics are useful later, they can remain local implementation detail rather than part of the initial public bus contract.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. First-wave user actions should stay local to the middleware/controller rather than becoming public bus commands.
|
||||
2. The first public `workspaceBus` contract should be notification-oriented.
|
||||
3. Capacity notifications should use absolute `0..1` progress rather than deltas.
|
||||
4. A minimal first-wave bus surface is enough: draft change, capacity change, apply requested, apply success, and apply failure.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a `decision` that fixes the minimal first-wave `workspaceBus` contract for `Bank Composition`.
|
||||
@ -1,98 +0,0 @@
|
||||
# Asset Bank Composition Persistence and Snapshot Propagation Agenda
|
||||
|
||||
Status: Open
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
When the developer clicks `apply`, the selected files for bank composition must be persisted and reflected back into runtime state.
|
||||
|
||||
That write path spans Studio and packer concerns:
|
||||
|
||||
- staged selected files must be serialized into `asset.json`;
|
||||
- the older `inputsByRole` shape should give way to the newer `artifacts` shape;
|
||||
- the minimal runtime snapshot must reflect the persisted result after apply.
|
||||
|
||||
## Context
|
||||
|
||||
The earlier agendas in this sequence assume `apply` may remain disabled or stubbed until persistence is ready.
|
||||
This agenda isolates the write-path discussion so the rest of the UI can progress first.
|
||||
|
||||
The current direction is already mostly known:
|
||||
|
||||
- persistence should happen through packer, not by having Studio write manifest files directly;
|
||||
- selected composition should be stored in `asset.json`;
|
||||
- runtime state should be refreshed after persistence so `Asset Details` stays coherent.
|
||||
|
||||
## Options
|
||||
|
||||
1. Let Studio write `asset.json` directly.
|
||||
2. Route `apply` through packer services and let packer own manifest persistence plus snapshot refresh.
|
||||
3. Persist only to runtime state first and defer manifest persistence.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
1. Direct manifest writes from Studio would bypass packer ownership and create duplicate write rules.
|
||||
2. A packer-owned write path is cleaner and aligns with existing asset mutation flows.
|
||||
3. Runtime-only persistence would create an unstable editing model and almost certainly drift from disk state.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Route `apply` through packer and persist selected files into `asset.json` using the newer `artifacts` representation.
|
||||
|
||||
Baseline expectations:
|
||||
|
||||
- `apply` submits the selected ordered files to packer;
|
||||
- packer updates `asset.json`;
|
||||
- packer propagates the resulting minimal state back into the runtime snapshot;
|
||||
- Studio refreshes the section from the updated details/snapshot state instead of trusting stale draft data.
|
||||
|
||||
### Persistence Baseline
|
||||
|
||||
The first-wave persistence direction is:
|
||||
|
||||
- `artifacts` replaces the older `inputsByRole` representation in `asset.json`;
|
||||
- the bank-composition selection should therefore persist through `artifacts`, not through a parallel legacy shape;
|
||||
- selected file order should remain explicit in persisted data rather than relying on array position alone.
|
||||
|
||||
### Apply Refresh and Failure Baseline
|
||||
|
||||
After `apply`, the Studio should not trust stale draft state.
|
||||
|
||||
The first-wave refresh baseline is:
|
||||
|
||||
- packer persists the selected ordered files into `asset.json`;
|
||||
- packer refreshes the minimal runtime snapshot state needed by `Asset Details`;
|
||||
- the Studio rebinds the section from the refreshed persisted state and returns the section to consistent read-only mode.
|
||||
|
||||
The minimum refreshed state should include:
|
||||
|
||||
- persisted `selected` rows;
|
||||
- the current `available` projection for details;
|
||||
- recalculated capacity state;
|
||||
- recalculated blockers or eligibility state relevant to the section.
|
||||
|
||||
If `apply` fails:
|
||||
|
||||
- the draft must not be discarded;
|
||||
- the section must remain in editing mode;
|
||||
- the middleware/controller should publish `BankCompositionApplyFailed`;
|
||||
- the UI should show a local error or hint surface;
|
||||
- the user should still be able to retry, reset, or cancel.
|
||||
|
||||
## Open Questions
|
||||
|
||||
No open questions remain in this agenda wave.
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed:
|
||||
|
||||
1. `artifacts` should replace the older `inputsByRole` shape rather than coexist with it for bank-composition persistence.
|
||||
2. After `apply`, packer should refresh the minimal snapshot state required by `Asset Details` and Studio should rebind from that refreshed persisted state.
|
||||
3. If `apply` fails, the draft remains intact, the section stays in editing mode, and the UI surfaces a local failure state while preserving retry, reset, and cancel.
|
||||
|
||||
## Next Suggested Step
|
||||
|
||||
Turn this into a cross-domain `decision` or a paired `docs/studio` + `docs/packer` decision set that closes the apply write path.
|
||||
@ -1,234 +0,0 @@
|
||||
# Asset Bank Composition Area - Dual List and Capacity Meter Agenda
|
||||
|
||||
Status: Open (Umbrella, split into follow-up agendas)
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Problem
|
||||
|
||||
The Studio `Assets` details area does not yet expose an explicit authoring surface for bank composition based on internal asset files.
|
||||
|
||||
The next planned area is not a simple form row.
|
||||
It combines:
|
||||
|
||||
- a left-side transfer area with `available files` and `files included in build`;
|
||||
- a right-side vertical capacity meter for fixed bank size usage;
|
||||
- rule-driven gating where files can no longer be moved into the build set once the bank reaches its fixed size limit.
|
||||
|
||||
This looks small in layout terms, but it hides many interaction details:
|
||||
|
||||
- which files are shown at all;
|
||||
- which files are build-eligible;
|
||||
- how diagnostics affect transfer availability;
|
||||
- whether order matters;
|
||||
- how the meter behaves near or above the limit;
|
||||
- and how Studio should explain hard capacity blockers without becoming noisy.
|
||||
|
||||
This topic needs a Studio agenda before it becomes a decision or implementation PR.
|
||||
|
||||
## Context
|
||||
|
||||
Recent packer work now gives the runtime snapshot enough information to support this UI discussion more concretely:
|
||||
|
||||
- available files per registered asset;
|
||||
- build-candidate files derived from the current walk;
|
||||
- file-scoped diagnostics kept segregated for future UI use;
|
||||
- measured bank size usage for the current build-candidate set;
|
||||
- stable asset identity through `asset_id` for registered assets only.
|
||||
|
||||
That means the Studio can now discuss this area against a real backend shape instead of inventing a purely visual placeholder.
|
||||
|
||||
Important constraints already known:
|
||||
|
||||
1. only registered assets should participate in this internal bank-composition flow;
|
||||
2. the snapshot should retain file inventory and build-candidate information, but not raw file bytes;
|
||||
3. bank size is fixed on the hardware/runtime side;
|
||||
4. when the bank reaches its maximum size, the UI must block adding more files into the build set.
|
||||
|
||||
## Current Code Context
|
||||
|
||||
The current Studio selected-asset details composition is still centered on:
|
||||
|
||||
- summary and actions;
|
||||
- runtime contract;
|
||||
- diagnostics and preview-related surfaces already present in the details flow.
|
||||
|
||||
Relevant code anchors today:
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/contract/AssetDetailsContractControl.java`
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
||||
|
||||
There is no existing `DualListView<T>` or dedicated bank-composition control in `prometeu-studio` yet.
|
||||
|
||||
That matters because this agenda is not only about layout.
|
||||
It is about how a new section inside `Asset Details` should behave and how its internal components should coordinate.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Create a dedicated `Bank Composition` section inside `Asset Details`, implemented as a `VBox` section just like the other asset-details sections, and explicitly backed by packer runtime data.
|
||||
|
||||
Operationally, this section should follow the same staged-editing pattern already used by `Runtime Contract`, including `change`, `apply`, `reset`, and `cancel` actions.
|
||||
|
||||
Recommended baseline shape:
|
||||
|
||||
1. left side of the section body: a dedicated `StudioDualListView<T>` component with:
|
||||
- left list = available files
|
||||
- right list = files included in build
|
||||
2. right side of the section body: a dedicated vertical `StudioAssetCapacityMeter` component showing current measured usage versus fixed bank capacity
|
||||
3. hard gating rule:
|
||||
if adding a file would exceed the fixed bank size, the move must be blocked before the item enters the build list
|
||||
4. coordination rule:
|
||||
the transfer list and the capacity meter must be built as components for this asset-workspace use case and must be able to exchange typed events through the `workspaceBus`
|
||||
|
||||
Why this direction:
|
||||
|
||||
- it gives bank composition its own didactic and operational area inside `Asset Details`;
|
||||
- it leaves room to discuss many smaller details without destabilizing the rest of selected-asset details;
|
||||
- it keeps authoring behavior aligned with the existing `Runtime Contract` section instead of inventing a second editing model inside `Asset Details`;
|
||||
- it aligns with the Studio event-driven workspace model already used by the `Assets` workspace.
|
||||
|
||||
### Component Direction
|
||||
|
||||
The first implementation should not treat these controls as isolated local widgets.
|
||||
|
||||
Rules:
|
||||
|
||||
- `StudioDualListView<T>` is the component name for the transfer-list surface of this section;
|
||||
- `StudioDualListView<T>` should be introduced as an abstract Studio component created for this bank-composition section;
|
||||
- `StudioDualListView<T>` should leave concrete behavior to subclasses, with capabilities added incrementally as real bank-composition needs appear;
|
||||
- `StudioAssetCapacityMeter` is the component name for the vertical capacity meter of this section;
|
||||
- `StudioAssetCapacityMeter` should also be introduced as a Studio component created for this bank-composition section;
|
||||
- both components must be able to publish and consume typed events through the `workspaceBus`;
|
||||
- the event model must allow coordination not only between the transfer list and the capacity meter, but also with surrounding details/workspace components when selection, eligibility, diagnostics, or staged apply behavior evolves;
|
||||
- the first event baseline should stay intentionally small:
|
||||
increase and decrease capacity updates expressed as percentage in the `0..1` range are enough to start;
|
||||
- the initial component scope is still bank-composition-specific, even if later refactoring makes them reusable elsewhere.
|
||||
|
||||
### Current Baseline Assumptions
|
||||
|
||||
The following points are now assumed for the current discussion wave:
|
||||
|
||||
1. `StudioDualListView<T>` is abstract, with concrete subclasses supplying bank-specific behavior over time.
|
||||
2. `Bank Composition` is always visible for the current asset families, because the currently active bank-based families are `Tile` and `Sound`.
|
||||
3. `available files` come directly from the snapshot projection derived from `walkResult`.
|
||||
4. only files without blocking diagnostics may appear in `available files`.
|
||||
5. file order in the right list affects build output and must be developer-controlled.
|
||||
6. the right list therefore needs ordering support and should surface indices as part of the UI.
|
||||
7. capacity computation is family-specific and must not be normalized prematurely into one fake universal formula.
|
||||
8. the bank-composition section should receive its data as part of the normal asset-details fetch.
|
||||
9. `StudioDualListView<T>` and `StudioAssetCapacityMeter` should both remain intentionally dumb; a bank-composition middleware/controller should own family-specific UI rules and hard-limit orchestration.
|
||||
10. if the Studio later needs non-bank-based asset handling, that should be introduced via another bank manager/composition manager rather than by overengineering this first wave.
|
||||
11. the section should use the same staged interaction model as `Runtime Contract`, with `change`, `apply`, `reset`, and `cancel`.
|
||||
|
||||
### Family-Specific Capacity Notes
|
||||
|
||||
The current bank-capacity semantics already differ by family:
|
||||
|
||||
- `Tile` banks are matrix-based.
|
||||
Example:
|
||||
a `256x256` indexed matrix with tiles configured as `32x32` yields `8x8 = 64` tile slots.
|
||||
If each selected build file contributes one `32x32` tile, the bank can contain at most `64` selected files.
|
||||
- `Sound` banks are byte-budget-based.
|
||||
The relevant measure is sample size in bytes, with a fixed bank capacity such as `1 MB`.
|
||||
|
||||
That means `StudioAssetCapacityMeter` must be driven by bank-family semantics rather than by one simplistic shared percentage algorithm hidden from the user.
|
||||
|
||||
### Meter Behavior Baseline
|
||||
|
||||
The current direction for the meter is explicitly game-like:
|
||||
|
||||
- a vertical progress-bar style meter that rises as the bank fills;
|
||||
- green, orange, and red severity bands instead of one neutral fill;
|
||||
- a percentage label below the bar;
|
||||
- supporting text or hint copy explaining that banks have fixed capacity and must not be exceeded;
|
||||
- hint text should also nudge the developer toward splitting or reorganizing the asset when the bank is too full.
|
||||
|
||||
Initial thresholds:
|
||||
|
||||
- green below `65%`
|
||||
- orange at `>= 65%` or `> 9/16`
|
||||
- red at `>= 95%` or `> 14/16`
|
||||
|
||||
Hard-limit interaction baseline:
|
||||
|
||||
- the UI should disable only moves from left to right when capacity is exhausted or the candidate item would overflow the bank;
|
||||
- moving items from right to left must remain possible;
|
||||
- ordering actions on the right list must remain possible;
|
||||
- the surface should still explain why add is blocked, instead of silently failing.
|
||||
|
||||
### Section Workflow Baseline
|
||||
|
||||
`Bank Composition` should not auto-persist edits while the developer is moving files around.
|
||||
|
||||
The first-wave workflow should mirror `Runtime Contract`:
|
||||
|
||||
- `change` enters editable mode;
|
||||
- list transfers, ordering, and capacity feedback happen inside the staged draft state;
|
||||
- `apply` persists the new composition;
|
||||
- `reset` returns the draft to the last persisted state while staying in the editing flow;
|
||||
- `cancel` exits editing and discards uncommitted draft changes.
|
||||
|
||||
This keeps the mental model of `Asset Details` consistent across sections and avoids mixing immediate-write behavior with staged authoring behavior in the same surface.
|
||||
|
||||
### Ordering Baseline
|
||||
|
||||
The current first-wave baseline for right-list ordering is:
|
||||
|
||||
- `move up`
|
||||
- `move down`
|
||||
- visible indices on the right/build list
|
||||
|
||||
Drag-and-drop may still be attractive later, but it is not yet required to validate the first wave.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. What exact first-wave event and controller contract should be defined together for the bank-composition flow, since the `workspaceBus` events and the bank-composition middleware/controller should evolve as one design surface?
|
||||
2. What exact explanatory text should the section show for tile-bank exhaustion versus sound-bank exhaustion so the user understands the capacity rule, not just the percentage?
|
||||
|
||||
### Resolved In This Agenda Wave
|
||||
|
||||
The following points are now closed for the first wave:
|
||||
|
||||
1. The UI-facing file-row structure should be a dedicated Studio DTO for any bank type.
|
||||
2. The first concrete `StudioDualListView<T>` subclass should be asset-details-specific.
|
||||
3. The event contract and middleware/controller shape should be designed together incrementally, without premature generalization.
|
||||
4. Detailed wording for family-specific explanatory copy can be deferred until the section contract is otherwise ready.
|
||||
|
||||
## Suggested Next Step
|
||||
|
||||
Do not implement the area yet.
|
||||
|
||||
This umbrella agenda is now intentionally split into focused follow-up agendas aligned to the proposed execution order:
|
||||
|
||||
1. snapshot transfer into details DTOs:
|
||||
[`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](./Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md)
|
||||
2. base component construction:
|
||||
[`Agenda-02-Asset-Bank-Composition-Base-Components.md`](./Agenda-02-Asset-Bank-Composition-Base-Components.md)
|
||||
3. `Bank Composition` section shell:
|
||||
[`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](./Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
||||
4. bank-composition middleware/controller:
|
||||
[`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](./Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
||||
5. middleware-driven interaction:
|
||||
[`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](./Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
6. persistence:
|
||||
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](./Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
|
||||
### Proposed Execution Order
|
||||
|
||||
The current proposed implementation order is:
|
||||
|
||||
1. transfer snapshot state into asset-details DTOs
|
||||
2. build the base and concrete UI components
|
||||
3. create the `Bank Composition` UI shell with no behavior
|
||||
4. introduce the bank-composition middleware/controller and staged DTO flow
|
||||
5. wire developer actions through middleware and `workspaceBus`
|
||||
6. persist the selected composition back through packer into `asset.json` and the minimal snapshot
|
||||
|
||||
This sequence is useful not only for implementation, but also for decision slicing:
|
||||
|
||||
- early decisions can close DTO and section-shape questions first;
|
||||
- middle decisions can close middleware and event-orchestration questions;
|
||||
- the final decision can close persistence into `asset.json` and minimal snapshot propagation.
|
||||
|
||||
The next correct step is to work these follow-up agendas in order and derive smaller `decision` records from them instead of trying to close the whole bank-composition architecture in one pass.
|
||||
@ -1,282 +0,0 @@
|
||||
# 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.
|
||||
@ -5,15 +5,8 @@ This directory contains active Studio discussion agendas.
|
||||
Active agendas:
|
||||
|
||||
- [`Palette Management in Studio Agenda.md`](./Palette%20Management%20in%20Studio%20Agenda.md)
|
||||
- [`Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md`](./Asset%20Bank%20Composition%20Area%20-%20Dual%20List%20and%20Capacity%20Meter%20Agenda.md)
|
||||
- [`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](./Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md)
|
||||
- [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](./Agenda-02-Asset-Bank-Composition-Base-Components.md)
|
||||
- [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](./Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
||||
- [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](./Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
||||
- [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](./Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
- [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](./Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
|
||||
The shell, UI foundations, components admission baselines, and the first asset workspace wave were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/).
|
||||
Closed Studio agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue.
|
||||
|
||||
## Purpose
|
||||
|
||||
|
||||
@ -1,110 +0,0 @@
|
||||
# Bank Composition Base Components Decision
|
||||
|
||||
Status: Decided
|
||||
Cycle: 2026-03
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Context
|
||||
|
||||
The `Bank Composition` section inside `Asset Details` depends on two new Studio components:
|
||||
|
||||
- `StudioDualListView<T>`
|
||||
- `StudioAssetCapacityMeter`
|
||||
|
||||
These components need a first-wave contract before the section shell, middleware, and persistence work can proceed safely.
|
||||
|
||||
The DTO projection boundary was already closed in:
|
||||
|
||||
- [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
|
||||
This decision closes the first-wave component direction discussed in:
|
||||
|
||||
- [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](../agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md)
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt narrow, bank-composition-scoped first-wave components.
|
||||
|
||||
The component choices are:
|
||||
|
||||
1. `StudioDualListView<T>` remains an abstract Studio component;
|
||||
2. the first concrete implementation is asset-details-specific;
|
||||
3. `StudioAssetCapacityMeter` is a dumb visual component for vertical capacity display;
|
||||
4. neither component should own bank-family product rules.
|
||||
|
||||
`StudioDualListView<T>` should expose only the hooks needed by the first `Bank Composition` wave:
|
||||
|
||||
- row text and/or row graphic projection;
|
||||
- current left and right collections;
|
||||
- current selection state;
|
||||
- move left-to-right;
|
||||
- move right-to-left;
|
||||
- `moveUp`;
|
||||
- `moveDown`;
|
||||
- visible right-list index refresh.
|
||||
|
||||
The first asset-details concrete subclass should render rows directly.
|
||||
Do not introduce a separate row-renderer abstraction in this first wave.
|
||||
|
||||
`StudioAssetCapacityMeter` starts with these baseline inputs:
|
||||
|
||||
- `progress` in the `0..1` range;
|
||||
- a label, including percentage text when needed;
|
||||
- a severity-band state;
|
||||
- optional hint text.
|
||||
|
||||
## Justification
|
||||
|
||||
This keeps component scope small and aligned with the current implementation plan.
|
||||
|
||||
The decision avoids two common mistakes:
|
||||
|
||||
- overengineering highly generic components before the first section exists;
|
||||
- burying section behavior directly inside `Asset Details` with no named component boundary.
|
||||
|
||||
Direct row rendering in the first concrete dual-list implementation is the pragmatic choice.
|
||||
There is no current evidence that a standalone row-renderer abstraction is needed.
|
||||
|
||||
Keeping `StudioAssetCapacityMeter` dumb also protects the future middleware/controller boundary.
|
||||
Family-specific rules should not leak into the visual component.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following constraints now apply:
|
||||
|
||||
1. `StudioDualListView<T>` must remain abstract in the first wave;
|
||||
2. the first concrete `StudioDualListView<T>` implementation belongs to the asset-details flow;
|
||||
3. right-list ordering support must include `moveUp`, `moveDown`, and visible indices;
|
||||
4. `StudioAssetCapacityMeter` must remain visual and state-driven, not rule-driven;
|
||||
5. bank-family capacity logic remains outside both components.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the Java package layout or exact class names for the first concrete asset-details subclass;
|
||||
- the `Bank Composition` section shell layout details;
|
||||
- the middleware/controller contract;
|
||||
- the `workspaceBus` event contract;
|
||||
- persistence or apply behavior.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- Studio agendas:
|
||||
[`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
||||
[`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
||||
[`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
- Studio specs:
|
||||
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Studio code:
|
||||
future component classes for `StudioDualListView<T>`, the first asset-details concrete implementation, and `StudioAssetCapacityMeter`
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Examples implied by this decision:
|
||||
|
||||
- the right/build list can be reordered through `moveUp` and `moveDown`;
|
||||
- the right/build list can display visible indices without requiring middleware-specific rendering logic;
|
||||
- the capacity meter can show green, orange, or red state based on inputs from higher-level orchestration without knowing tile or sound rules.
|
||||
@ -1,109 +0,0 @@
|
||||
# Bank Composition Details DTO Projection Decision
|
||||
|
||||
Status: Decided
|
||||
Cycle: 2026-03
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Context
|
||||
|
||||
The `Bank Composition` section inside `Asset Details` needs a stable UI-facing data shape before component, middleware, and persistence work can proceed.
|
||||
|
||||
The source information comes from two distinct places:
|
||||
|
||||
- runtime snapshot state derived from `walkResult`, which should feed `available` files;
|
||||
- persisted `asset.json` composition state, which should feed `selected` files.
|
||||
|
||||
The Studio should not bind section UI directly to snapshot internals or raw manifest structures.
|
||||
This needs a Studio-owned DTO projection boundary.
|
||||
|
||||
This decision closes the DTO direction discussed in:
|
||||
|
||||
- [`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](../agendas/Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md)
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt one dedicated Studio-owned DTO family for `Bank Composition` details data.
|
||||
|
||||
The first-wave projection rules are:
|
||||
|
||||
1. snapshot rows derived from `walkResult` become `available` rows in the Studio DTO layer;
|
||||
2. persisted composition rows from `asset.json` become `selected` rows in the Studio DTO layer;
|
||||
3. both flows must be projected into Studio DTOs before reaching `Asset Details` UI code;
|
||||
4. the DTO family must be generic enough to support any bank type, even if family-specific fields are added later;
|
||||
5. the DTO field set must stay intentionally small and grow only when concrete UI behavior requires it.
|
||||
|
||||
The first DTO revision starts with these fields:
|
||||
|
||||
- `path`
|
||||
- `displayName`
|
||||
- `size`
|
||||
- `lastModified`
|
||||
- `fingerprint`
|
||||
- `metadata`
|
||||
|
||||
Availability and ordering rules are:
|
||||
|
||||
1. only non-blocking files become `available` DTO rows;
|
||||
2. blocking files must not be projected into the `Bank Composition` DTO layer;
|
||||
3. UI ordering is visual in the selected list;
|
||||
4. persisted ordering in `asset.json` should use an explicit index representation such as `{ file, index }`.
|
||||
|
||||
## Justification
|
||||
|
||||
This direction keeps the Studio UI decoupled from packer/runtime internal shapes while still using runtime data as the source of truth.
|
||||
|
||||
One shared DTO family is the pragmatic middle ground:
|
||||
|
||||
- lighter than separate `available` and `selected` row models;
|
||||
- safer than direct binding to snapshot and manifest structures;
|
||||
- easier to reuse across section shell, transfer list, meter, and staged editing middleware.
|
||||
|
||||
Filtering blocking files before DTO projection also keeps the section contract simpler.
|
||||
The UI should receive only rows that are actually eligible to appear as `available`.
|
||||
|
||||
Persisted order needs an explicit index in `asset.json` because list order is not a robust persistence contract by itself.
|
||||
|
||||
## Implications
|
||||
|
||||
The Studio details layer now owns a DTO projection step for `Bank Composition`.
|
||||
|
||||
This means:
|
||||
|
||||
- component work should consume Studio DTOs, not packer snapshot rows directly;
|
||||
- middleware work should operate on DTO-based staged state;
|
||||
- persistence work must translate selected DTO order into indexed `asset.json` entries;
|
||||
- packer-facing details fetches must expose enough source data to populate the DTO fields above.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact Java classes or package layout for the DTOs;
|
||||
- the section middleware/controller contract;
|
||||
- the `workspaceBus` event contract;
|
||||
- the concrete `asset.json` `artifacts` schema beyond the need for explicit indexed order;
|
||||
- family-specific explanatory copy for tile versus sound exhaustion.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- Studio agendas:
|
||||
[`Agenda-02-Asset-Bank-Composition-Base-Components.md`](../agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md)
|
||||
[`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
||||
[`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
||||
[`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
- Studio specs:
|
||||
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Studio code:
|
||||
`Asset Details` details fetch, DTO projection layer, and `Bank Composition` section inputs
|
||||
- Packer code and docs:
|
||||
details payload shaping and future `asset.json` persistence under the `artifacts` composition path
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Examples implied by this decision:
|
||||
|
||||
- a file with blocking diagnostics does not produce an `available` DTO row at all;
|
||||
- a selected file may appear in the UI with visual order `3`, while persistence writes something like `{ file: "...", index: 3 }`;
|
||||
- adding new UI needs later should extend the DTO deliberately instead of pulling snapshot internals straight into the section.
|
||||
@ -1,114 +0,0 @@
|
||||
# Bank Composition Middleware and Staged Editing Decision
|
||||
|
||||
Status: Decided
|
||||
Cycle: 2026-03
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Context
|
||||
|
||||
`Bank Composition` needs a section-scoped coordinator above the new UI components because:
|
||||
|
||||
- `StudioDualListView<T>` is intentionally dumb;
|
||||
- `StudioAssetCapacityMeter` is intentionally dumb;
|
||||
- the section must follow the same staged-edit model already used elsewhere in `Asset Details`;
|
||||
- capacity and blocker rules differ by asset family.
|
||||
|
||||
The current codebase already has a staged-edit primitive in:
|
||||
|
||||
- [`StudioFormSession.java`](../../../prometeu-studio/src/main/java/p/studio/controls/forms/StudioFormSession.java)
|
||||
|
||||
The earlier `Bank Composition` decisions already fixed:
|
||||
|
||||
- DTO projection:
|
||||
[`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
- base components:
|
||||
[`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md)
|
||||
- section shell:
|
||||
[`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md)
|
||||
|
||||
This decision closes the middleware direction discussed in:
|
||||
|
||||
- [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt a dedicated bank-composition section-scoped coordinator built around `StudioFormSession<BankCompositionDraft>`.
|
||||
|
||||
The first-wave rules are:
|
||||
|
||||
1. `StudioFormSession<BankCompositionDraft>` is the shared staged-edit core for the section;
|
||||
2. `Bank Composition` must not introduce a second session model parallel to `StudioFormSession`;
|
||||
3. family-specific variation must not come from subclassing `StudioFormSession`;
|
||||
4. family-specific variation must come from draft factories and bank-composition policies offered per asset family;
|
||||
5. `apply` may remain stubbed or disabled until persistence is wired, but the session contract should already exist.
|
||||
|
||||
The section-scoped coordinator owns orchestration around the form session, including:
|
||||
|
||||
- translating persisted section state into session source/draft state;
|
||||
- beginning edit mode;
|
||||
- resetting draft state;
|
||||
- canceling edits;
|
||||
- applying draft state when persistence is available;
|
||||
- evaluating transfer eligibility;
|
||||
- evaluating reorder effects;
|
||||
- calculating capacity state;
|
||||
- calculating hard-limit blockers and hints.
|
||||
|
||||
The section-scoped coordinator should publish one section-facing view model that includes:
|
||||
|
||||
- shell state such as editing mode, dirty state, and action availability;
|
||||
- left and right list state;
|
||||
- capacity-meter state;
|
||||
- blockers and hint text when relevant.
|
||||
|
||||
## Justification
|
||||
|
||||
This is the simplest design that matches the actual codebase.
|
||||
|
||||
`StudioFormSession` already provides the staged-edit lifecycle the section needs.
|
||||
Creating a second coordinator-specific session model would duplicate behavior for no gain.
|
||||
|
||||
At the same time, subclassing `StudioFormSession` is the wrong variation point.
|
||||
The current class is final, and more importantly the lifecycle does not change by asset family.
|
||||
What changes by family is bank-composition logic: draft shaping, eligibility, capacity, and blockers.
|
||||
|
||||
That makes policies and factories the correct seam.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following constraints now apply:
|
||||
|
||||
1. `StudioFormSession<BankCompositionDraft>` is the only staged-edit core for the section in the first wave;
|
||||
2. asset-family differences must be modeled outside `StudioFormSession`;
|
||||
3. the section-scoped coordinator remains section-specific and should not become a platform-wide bank manager abstraction;
|
||||
4. dumb UI components consume derived state and do not own bank rules;
|
||||
5. the section-facing output must be consolidated into one view model rather than scattered state channels.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact Java class names or package layout for the section-scoped coordinator, policies, or draft factories;
|
||||
- the exact shape of `BankCompositionDraft`;
|
||||
- the `workspaceBus` event contract;
|
||||
- persistence/apply integration with packer;
|
||||
- the exact text of family-specific hint and blocker messages.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- Studio agendas:
|
||||
[`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
- Studio specs:
|
||||
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Studio code:
|
||||
`StudioFormSession` integration, `Bank Composition` section-scoped coordinator, family-specific draft factories, and family-specific bank-composition policies
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Examples implied by this decision:
|
||||
|
||||
- a tile family and a sound family can share the same `StudioFormSession` lifecycle while using different capacity/blocker policies;
|
||||
- the dual list and meter can stay dumb because the section-scoped coordinator supplies already-derived state;
|
||||
- when persistence is not wired yet, `beginEdit`, `reset`, and `cancel` still work through the shared form-session model.
|
||||
@ -1,120 +0,0 @@
|
||||
# Bank Composition Persistence and Snapshot Propagation Decision
|
||||
|
||||
Status: Decided
|
||||
Cycle: 2026-03
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Context
|
||||
|
||||
`Bank Composition` reaches across Studio and packer when the developer clicks `apply`.
|
||||
|
||||
That write path must:
|
||||
|
||||
- persist selected ordered files into `asset.json`;
|
||||
- use the newer `artifacts` representation instead of the older `inputsByRole` shape;
|
||||
- refresh enough runtime state for `Asset Details` to become consistent again after apply.
|
||||
|
||||
The earlier `Bank Composition` decisions already fixed:
|
||||
|
||||
- DTO projection:
|
||||
[`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
- base components:
|
||||
[`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md)
|
||||
- section shell:
|
||||
[`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md)
|
||||
- middleware and staged editing:
|
||||
[`Bank Composition Middleware and Staged Editing Decision.md`](./Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md)
|
||||
- workspace bus interaction:
|
||||
[`Bank Composition WorkspaceBus Interaction Decision.md`](./Bank%20Composition%20WorkspaceBus%20Interaction%20Decision.md)
|
||||
|
||||
This decision closes the persistence direction discussed in:
|
||||
|
||||
- [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
|
||||
## Decision
|
||||
|
||||
Route `Bank Composition` apply through packer and persist selection under `asset.json` `artifacts`.
|
||||
|
||||
The first-wave rules are:
|
||||
|
||||
1. Studio must not write `asset.json` directly;
|
||||
2. the packer service owns validation, persistence, and minimal snapshot refresh for selected bank-composition files;
|
||||
3. `artifacts` replaces the older `inputsByRole` representation for this flow;
|
||||
4. selected file order must remain explicit in persisted data rather than relying on array position alone;
|
||||
5. after a successful apply, Studio must refresh from persisted state rather than trusting stale draft state.
|
||||
|
||||
The minimal successful apply flow is:
|
||||
|
||||
1. Studio submits the selected ordered files to the packer service;
|
||||
2. packer updates `asset.json` under the `artifacts` representation;
|
||||
3. packer refreshes the minimal runtime snapshot state required by `Asset Details`;
|
||||
4. Studio rebinds the section from that refreshed persisted state;
|
||||
5. the section returns to consistent read-only mode.
|
||||
|
||||
The minimum refreshed state after apply must include:
|
||||
|
||||
- persisted `selected` rows;
|
||||
- the current `available` projection used by `Asset Details`;
|
||||
- recalculated capacity state;
|
||||
- recalculated blockers or eligibility state relevant to the section.
|
||||
|
||||
The failure rules are:
|
||||
|
||||
1. if apply fails, the draft must not be discarded;
|
||||
2. the section must remain in editing mode;
|
||||
3. the middleware/controller should publish `BankCompositionApplyFailed`;
|
||||
4. the UI should show a local failure surface;
|
||||
5. the user must still be able to retry, reset, or cancel.
|
||||
|
||||
## Justification
|
||||
|
||||
This keeps write ownership in the correct domain boundary.
|
||||
|
||||
Packer already owns asset mutation and runtime refresh logic.
|
||||
Letting Studio write manifests directly would duplicate rules and create drift between UI and runtime behavior.
|
||||
|
||||
The Studio should only submit the apply request and react to the result.
|
||||
The packer service is the owner of validation, persistence, and state propagation.
|
||||
|
||||
Refreshing from persisted state after success is also necessary.
|
||||
Otherwise the section would keep trusting stale draft state and could diverge from what packer actually accepted and wrote.
|
||||
|
||||
Preserving the draft on failure is the correct staged-edit behavior.
|
||||
The user should not lose work because persistence failed.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following constraints now apply:
|
||||
|
||||
1. Studio is not the manifest writer for `Bank Composition`;
|
||||
2. `artifacts` is the persistence path for selected bank-composition files;
|
||||
3. `inputsByRole` is not the write target for this flow;
|
||||
4. successful apply requires snapshot refresh before the section settles back to read-only mode;
|
||||
5. failed apply must preserve draft state and editing mode.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact final `asset.json` `artifacts` schema beyond explicit ordered file persistence;
|
||||
- the concrete packer request/response message names;
|
||||
- the exact Java event class payloads for apply success or failure;
|
||||
- broader manifest migration strategy outside this `Bank Composition` flow.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- Studio specs:
|
||||
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Studio code:
|
||||
bank-composition apply flow, failure handling, and section refresh behavior
|
||||
- Packer docs and code:
|
||||
`asset.json` `artifacts` persistence, write-path integration, and minimal runtime snapshot refresh after apply
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Examples implied by this decision:
|
||||
|
||||
- after a successful apply, the section should reload from the refreshed persisted state instead of keeping the old draft instance;
|
||||
- if packer rejects an apply, the selected rows remain in the draft so the user can adjust and retry;
|
||||
- selected bank-composition files must be written through `artifacts`, not through `inputsByRole`.
|
||||
@ -1,85 +0,0 @@
|
||||
# Bank Composition Section Shell Decision
|
||||
|
||||
Status: Decided
|
||||
Cycle: 2026-03
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Context
|
||||
|
||||
The `Bank Composition` area needs a visible section shell inside `Asset Details` before behavior and persistence are wired.
|
||||
|
||||
The section should not invent a parallel editing model.
|
||||
It needs to align with the existing `Asset Details` section rhythm, especially `Runtime Contract`.
|
||||
|
||||
The DTO projection boundary and the first-wave component direction were already closed in:
|
||||
|
||||
- [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
- [`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md)
|
||||
|
||||
This decision closes the shell direction discussed in:
|
||||
|
||||
- [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md)
|
||||
|
||||
## Decision
|
||||
|
||||
Create the `Bank Composition` section shell early, before full behavior is implemented.
|
||||
|
||||
The shell contract is:
|
||||
|
||||
1. `Bank Composition` is a `VBox` section inside `Asset Details`;
|
||||
2. the section shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level;
|
||||
3. the section should align with the existing `FormSession` staged-editing pattern;
|
||||
4. the section header and action cluster must support `change`, `apply`, `reset`, and `cancel`;
|
||||
5. the body layout must reserve the dual-list region on the left and the capacity-meter region on the right;
|
||||
6. outside `change` mode, the section should render the current persisted state as read-only;
|
||||
7. before middleware wiring exists, the section body should still render disabled or read-only internals rather than an empty placeholder.
|
||||
|
||||
## Justification
|
||||
|
||||
This keeps the editing model of `Asset Details` coherent.
|
||||
|
||||
The developer should not need to learn one staged-edit contract for `Runtime Contract` and another for `Bank Composition`.
|
||||
Using the same shell and `FormSession` rhythm lowers implementation risk and reduces UI inconsistency.
|
||||
|
||||
Rendering the current persisted state in read-only mode is also the better default.
|
||||
It teaches the surface, shows that data exists, and avoids making the section look unfinished or absent whenever editing is not active.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following constraints now apply:
|
||||
|
||||
1. `Bank Composition` must exist as a real section shell before middleware behavior is complete;
|
||||
2. the shell must follow the same staged-edit interaction model already used by `Runtime Contract`;
|
||||
3. `FormSession` is part of the expected section lifecycle;
|
||||
4. the section must not collapse into a blank placeholder when behavior is still incomplete;
|
||||
5. the shell layout must already reflect the intended dual-list plus capacity-meter structure.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the middleware/controller contract;
|
||||
- the `workspaceBus` event contract;
|
||||
- the exact disabled/read-only visuals of the early shell;
|
||||
- apply persistence behavior;
|
||||
- family-specific meter semantics beyond the already agreed general direction.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- Studio agendas:
|
||||
[`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md)
|
||||
[`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
- Studio specs:
|
||||
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Studio code:
|
||||
`AssetDetailsControl`, the future `Bank Composition` section control, and any `FormSession` integration needed for staged editing
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Examples implied by this decision:
|
||||
|
||||
- the section can appear in the details view even before middleware logic exists;
|
||||
- the shell can show current selection state in read-only mode when the user has not entered `change`;
|
||||
- the same section-level action rhythm used by `Runtime Contract` should apply to `Bank Composition`.
|
||||
@ -1,110 +0,0 @@
|
||||
# Bank Composition WorkspaceBus Interaction Decision
|
||||
|
||||
Status: Decided
|
||||
Cycle: 2026-03
|
||||
Domain Owner: `docs/studio`
|
||||
Cross-Domain Impact: `docs/packer`
|
||||
|
||||
## Context
|
||||
|
||||
The `Bank Composition` section should integrate with the Studio workspace event model, but the first-wave `workspaceBus` surface needs to stay intentionally small.
|
||||
|
||||
The previous decisions already fixed:
|
||||
|
||||
- DTO projection:
|
||||
[`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
- base components:
|
||||
[`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md)
|
||||
- section shell:
|
||||
[`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md)
|
||||
- middleware and staged editing:
|
||||
[`Bank Composition Middleware and Staged Editing Decision.md`](./Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md)
|
||||
|
||||
This decision closes the first-wave event direction discussed in:
|
||||
|
||||
- [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md)
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt a minimal, notification-oriented first-wave `workspaceBus` contract for `Bank Composition`.
|
||||
|
||||
The first-wave rules are:
|
||||
|
||||
1. user actions should stay local to the bank-composition section-scoped coordinator whenever possible;
|
||||
2. the first public `workspaceBus` surface should publish only state transitions or lifecycle notifications that matter outside the section;
|
||||
3. the event contract must not encode bank-family product rules directly into event types;
|
||||
4. capacity notifications should use absolute progress in the `0..1` range, not deltas.
|
||||
|
||||
The first-wave public notification set is:
|
||||
|
||||
- `BankCompositionDraftChanged`
|
||||
- `BankCompositionCapacityChanged`
|
||||
- `BankCompositionApplyRequested`
|
||||
- `BankCompositionApplied`
|
||||
- `BankCompositionApplyFailed`
|
||||
|
||||
The first-wave local-only action set remains inside the section-scoped coordinator:
|
||||
|
||||
- `beginEdit`
|
||||
- `moveToSelected`
|
||||
- `moveToAvailable`
|
||||
- `moveUp`
|
||||
- `moveDown`
|
||||
- `reset`
|
||||
- `cancel`
|
||||
- `apply`
|
||||
|
||||
`apply` should remain a local section action that calls the packer service.
|
||||
It is not a public bus command in the first wave.
|
||||
|
||||
The first-wave capacity notification should expose at least:
|
||||
|
||||
- `progress`
|
||||
- `severity`
|
||||
- `blocked`
|
||||
|
||||
## Justification
|
||||
|
||||
This preserves the workspace event architecture without inflating the bus contract too early.
|
||||
|
||||
If every section interaction became a public event, the bus would turn into a noisy command surface with little external value.
|
||||
The section-scoped coordinator is already the right local place for section commands and recalculation.
|
||||
|
||||
Absolute capacity state is also the right public shape.
|
||||
It is easier to consume, easier to reason about, and safer for late subscribers than delta-based updates.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
The following constraints now apply:
|
||||
|
||||
1. the first-wave public bus contract is notification-oriented, not command-oriented;
|
||||
2. section-local interactions should not become public events unless another subscriber truly needs them;
|
||||
3. capacity state must be published as absolute progress;
|
||||
4. the bus contract must stay bank-family-neutral at the event-type level.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact Java class names or package layout for the new events;
|
||||
- the full payload shape of each event beyond the minimum capacity fields already fixed;
|
||||
- whether future cross-section coordination will require more bus events;
|
||||
- apply persistence semantics with packer.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- Studio agendas:
|
||||
[`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md)
|
||||
- Studio specs:
|
||||
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Studio code:
|
||||
bank-composition section-scoped coordinator, event definitions, and event subscribers in `Asset Details`
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Examples implied by this decision:
|
||||
|
||||
- dragging or reordering inside the dual list does not require a public bus command in the first wave;
|
||||
- the capacity meter can react to a published absolute progress state such as `0.72` with `orange` severity and `blocked=false`;
|
||||
- apply success or failure can be observed outside the section without exposing every internal section action as a bus event;
|
||||
- clicking `apply` should call the packer service locally and only publish lifecycle notifications around that operation.
|
||||
@ -1,179 +0,0 @@
|
||||
# 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.
|
||||
@ -1,17 +1,12 @@
|
||||
# Studio Decisions
|
||||
|
||||
This directory contains Studio decision records.
|
||||
This directory contains Studio decision records that still need propagation.
|
||||
|
||||
Current decision records:
|
||||
Current retained set:
|
||||
|
||||
- [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
- [`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md)
|
||||
- [`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md)
|
||||
- [`Bank Composition Middleware and Staged Editing Decision.md`](./Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md)
|
||||
- [`Bank Composition WorkspaceBus Interaction Decision.md`](./Bank%20Composition%20WorkspaceBus%20Interaction%20Decision.md)
|
||||
- [`Bank Composition Persistence and Snapshot Propagation Decision.md`](./Bank%20Composition%20Persistence%20and%20Snapshot%20Propagation%20Decision.md)
|
||||
- none
|
||||
|
||||
The first Studio decision wave and the first asset workspace wave were already consolidated into:
|
||||
The current Studio decision wave has already been consolidated into:
|
||||
|
||||
- normative specifications under [`../specs/`](../specs/)
|
||||
- didactic material under [`../learn/`](../learn/)
|
||||
|
||||
@ -49,4 +49,8 @@ Start here:
|
||||
1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md)
|
||||
2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
|
||||
3. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
||||
4. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
4. [`assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
|
||||
5. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
6. [`bank-composition-editor.md`](./bank-composition-editor.md)
|
||||
7. [`pack-wizard-shell.md`](./pack-wizard-shell.md)
|
||||
8. [`project-scoped-state-and-activity.md`](./project-scoped-state-and-activity.md)
|
||||
|
||||
88
docs/studio/learn/assets-workspace-execution-wave.md
Normal file
88
docs/studio/learn/assets-workspace-execution-wave.md
Normal file
@ -0,0 +1,88 @@
|
||||
# Assets Workspace Execution Wave
|
||||
|
||||
## Original Problem
|
||||
|
||||
The first `Assets` workspace wave solved many UI problems in small execution slices:
|
||||
|
||||
- workspace foundation;
|
||||
- asset navigator;
|
||||
- selected-asset details;
|
||||
- activity, progress, and logs;
|
||||
- staged mutations;
|
||||
- event-driven refactor;
|
||||
- package and subscription boundaries.
|
||||
|
||||
That historical sequence was useful while implementation was in flight, but it became a poor learning surface.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable Studio direction for `Assets` is:
|
||||
|
||||
1. the workspace is asset-first, not file-first;
|
||||
2. the workspace is event-driven, not refresh-heavy;
|
||||
3. composition, projection, and rendering are separated;
|
||||
4. details sections update independently instead of forcing whole-panel rebuilds;
|
||||
5. mutation review is preview-first;
|
||||
6. the shell reflects operational lifecycle without taking over workspace-local reasoning.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Workspace Foundation
|
||||
|
||||
- `Assets` is a real workspace, not a placeholder;
|
||||
- workspace state is explicit about loading, empty, error, and ready conditions;
|
||||
- selection is stable by asset identity rather than by transient row position.
|
||||
|
||||
### 2. Navigator and Details Split
|
||||
|
||||
- the left side owns navigation and projection;
|
||||
- the main area teaches the selected asset in a fixed didactic order;
|
||||
- navigator updates and details updates must not require a workspace-wide redraw by default.
|
||||
|
||||
### 3. Event-Driven Ownership
|
||||
|
||||
- local UI change flows through typed workspace events;
|
||||
- component-scoped subscriptions replace root-owned redraw logic;
|
||||
- structural sync and local projection updates stay distinct.
|
||||
|
||||
### 4. Operational Surfaces
|
||||
|
||||
- activity belongs to the shell timeline;
|
||||
- progress belongs both to the current workspace flow and the broader shell context;
|
||||
- textual logs are supporting drill-down, not the main explanation surface.
|
||||
|
||||
### 5. Mutation Review
|
||||
|
||||
- preview is the default review surface for sensitive actions;
|
||||
- blockers, warnings, and safe fixes remain semantically separate;
|
||||
- modal confirmation is reserved for high-risk commit boundaries.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why the root should not own every redraw
|
||||
|
||||
If one asset row changes because its diagnostics changed, the correct response is a row-scoped update.
|
||||
Rebuilding navigator, details, and unrelated controls teaches the wrong ownership model and makes the UI harder to reason about.
|
||||
|
||||
### Example: Why the shell still needs activity
|
||||
|
||||
Mutation review happens inside the workspace.
|
||||
But lifecycle milestones such as `preview ready`, `action applied`, or `action failed` still matter at shell scope because they are part of the user's project timeline.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating `Assets` as a filesystem explorer with extra badges.
|
||||
- Using `refresh()` as the default answer to local UI state changes.
|
||||
- Letting details sections depend on a monolithic selected-asset redraw.
|
||||
- Using logs as the primary explanation surface for mutations.
|
||||
- Publishing shell activity without keeping workspace-local review visible.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
||||
- [`./mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
- [`./mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
|
||||
126
docs/studio/learn/bank-composition-editor.md
Normal file
126
docs/studio/learn/bank-composition-editor.md
Normal file
@ -0,0 +1,126 @@
|
||||
# Bank Composition Editor
|
||||
|
||||
## Original Problem
|
||||
|
||||
`Bank Composition` needed to become a real editor inside `Asset Details` without collapsing into any of these bad outcomes:
|
||||
|
||||
- direct binding to raw snapshot or manifest shapes;
|
||||
- overgeneric UI components before the first section existed;
|
||||
- family-specific rules hidden inside visual controls;
|
||||
- direct Studio writes to `asset.json`;
|
||||
- public bus chatter for every local section interaction.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The first-wave `Bank Composition` model is:
|
||||
|
||||
1. Studio owns a DTO projection boundary for the section;
|
||||
2. the section shell lands early and follows the existing staged-edit rhythm;
|
||||
3. dual-list and capacity-meter components stay intentionally dumb;
|
||||
4. one section-scoped coordinator around `StudioFormSession<BankCompositionDraft>` owns orchestration;
|
||||
5. public workspace-bus events stay minimal and notification-oriented;
|
||||
6. `apply` goes through packer and rebinds from refreshed persisted state.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. DTO Boundary
|
||||
|
||||
The section never consumes raw packer/runtime structures directly.
|
||||
|
||||
It works with Studio-owned DTOs for:
|
||||
|
||||
- `available` rows from current runtime/details state;
|
||||
- `selected` rows from persisted composition state.
|
||||
|
||||
Only non-blocking files enter the `available` DTO projection.
|
||||
|
||||
### 2. Section Shell
|
||||
|
||||
`Bank Composition` is a real `Asset Details` section, not a hidden future placeholder.
|
||||
|
||||
The shell follows the existing staged-edit rhythm:
|
||||
|
||||
- `change`
|
||||
- `apply`
|
||||
- `reset`
|
||||
- `cancel`
|
||||
|
||||
Outside edit mode, it teaches the current persisted state in read-only form.
|
||||
|
||||
### 3. Dumb Components
|
||||
|
||||
Two named components exist for this area:
|
||||
|
||||
- `StudioDualListView<T>`
|
||||
- `StudioAssetCapacityMeter`
|
||||
|
||||
They are intentionally state-driven, not rule-driven.
|
||||
Family-specific transfer, ordering, and capacity semantics do not live inside these components.
|
||||
|
||||
### 4. Section-Scoped Coordinator
|
||||
|
||||
The main orchestration lives in one section-scoped coordinator built around `StudioFormSession<BankCompositionDraft>`.
|
||||
|
||||
That coordinator owns:
|
||||
|
||||
- draft lifecycle;
|
||||
- transfer and reorder effects;
|
||||
- capacity state;
|
||||
- blockers and hints;
|
||||
- apply success and failure handling.
|
||||
|
||||
### 5. WorkspaceBus Boundary
|
||||
|
||||
The public bus surface stays intentionally small.
|
||||
|
||||
First-wave public notifications are about observable state transitions:
|
||||
|
||||
- draft changed;
|
||||
- capacity changed;
|
||||
- apply requested;
|
||||
- apply succeeded;
|
||||
- apply failed.
|
||||
|
||||
Local edit actions remain local to the section coordinator.
|
||||
|
||||
### 6. Persistence Boundary
|
||||
|
||||
Studio does not write `asset.json` directly for `Bank Composition`.
|
||||
|
||||
The write path is:
|
||||
|
||||
1. Studio submits ordered selected files to packer;
|
||||
2. packer validates and persists through `asset.json.artifacts`;
|
||||
3. packer refreshes the minimum runtime/details state;
|
||||
4. Studio rebinds from refreshed persisted state.
|
||||
|
||||
If apply fails, the draft stays alive and the section remains in editing mode.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why the meter must stay dumb
|
||||
|
||||
Tile banks and sound banks may calculate capacity differently.
|
||||
That difference belongs in family policies owned by the coordinator, not in `StudioAssetCapacityMeter`.
|
||||
|
||||
### Example: Why `apply` is not a public bus command
|
||||
|
||||
External observers may care that apply was requested or failed.
|
||||
They do not need to own the local section command sequence for `moveUp`, `moveDown`, `reset`, or `cancel`.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Binding section UI directly to raw snapshot rows or raw manifest shape.
|
||||
- Hiding bank-family rules inside `StudioDualListView<T>` or the capacity meter.
|
||||
- Creating a second staged-edit session model parallel to `StudioFormSession`.
|
||||
- Turning every local section action into a public workspace-bus event.
|
||||
- Writing `asset.json` directly from Studio instead of routing through packer.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
|
||||
87
docs/studio/learn/pack-wizard-shell.md
Normal file
87
docs/studio/learn/pack-wizard-shell.md
Normal file
@ -0,0 +1,87 @@
|
||||
# Pack Wizard Shell
|
||||
|
||||
## Original Problem
|
||||
|
||||
The `Assets` workspace already had a reserved `Pack` action, but that did not answer the real product question:
|
||||
|
||||
How should Studio behave when the developer wants to pack the current build set?
|
||||
|
||||
The risk was building a visually plausible modal that quietly reimplemented packer semantics or hid the real operational phases.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable first-wave rule is:
|
||||
|
||||
`Pack` is a Studio-owned wizard shell over packer-owned operations.
|
||||
|
||||
The wizard is phase-based:
|
||||
|
||||
1. `Summary`
|
||||
2. `Validation`
|
||||
3. `Packing`
|
||||
4. `Result`
|
||||
|
||||
Studio owns presentation and state binding.
|
||||
Packer owns summary, validation, execution, progress, and result semantics.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Workspace-Level Entry Point
|
||||
|
||||
- `Pack` is a workspace action, not a selected-asset action;
|
||||
- the user is operating on the current pack set, not on one asset in isolation.
|
||||
|
||||
### 2. Summary
|
||||
|
||||
- the wizard asks packer for the current build-set summary;
|
||||
- Studio does not count navigator rows and pretend that is the build set;
|
||||
- the canonical runtime artifact is explicitly `assets.pa`.
|
||||
|
||||
### 3. Validation
|
||||
|
||||
- validation runs only on `registered + included in build`;
|
||||
- blocking diagnostics stop the flow before execution;
|
||||
- warnings may be visible, but they do not become blockers unless packer classifies them that way.
|
||||
|
||||
### 4. Packing
|
||||
|
||||
- execution is operational and non-editable;
|
||||
- progress comes from packer-owned progress state or events;
|
||||
- the UI does not simulate progress with timers;
|
||||
- the first wave is non-cancelable.
|
||||
|
||||
### 5. Result
|
||||
|
||||
- the primary summary shows final status, packed asset count, elapsed time, and `assets.pa`;
|
||||
- companion artifacts are supporting detail, not the headline of the result screen;
|
||||
- the UI must distinguish blocked, failed, and successful outcomes.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why validation is a separate phase
|
||||
|
||||
If the wizard jumps straight from summary into execution, the user loses the explicit gate that explains why packing is blocked.
|
||||
Validation exists to make the gate understandable before byte emission begins.
|
||||
|
||||
### Example: Why Studio must not fake progress
|
||||
|
||||
A fake progress bar may look smoother, but it lies about operational ownership.
|
||||
If the packer is the owner of execution semantics, the UI must reflect packer-owned progress honestly.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating pack summary as a local Studio recomputation.
|
||||
- Using one opaque modal state instead of explicit operational phases.
|
||||
- Letting unrelated assets influence wizard validation.
|
||||
- Exposing fake cancel behavior that the packer does not actually support.
|
||||
- Making companion artifacts dominate the main result summary.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- Cross-domain:
|
||||
- [`../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md`](../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md)
|
||||
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
|
||||
57
docs/studio/learn/project-scoped-state-and-activity.md
Normal file
57
docs/studio/learn/project-scoped-state-and-activity.md
Normal file
@ -0,0 +1,57 @@
|
||||
# Project-Scoped State and Activity
|
||||
|
||||
## Original Problem
|
||||
|
||||
Some Studio state is global by nature, but some state is clearly tied to one opened project.
|
||||
|
||||
If project-local state is stored as if it were application-global, the shell starts mixing unrelated histories and the project root stops being the obvious home of Studio-owned project data.
|
||||
|
||||
## Consolidated Decision
|
||||
|
||||
The stable direction is:
|
||||
|
||||
1. project-local Studio state lives under `.studio/` inside the project root;
|
||||
2. shell activity is restored and persisted per project;
|
||||
3. persisted activity history is bounded;
|
||||
4. `.studio/` is the reserved root for future project-local Studio settings.
|
||||
|
||||
## Final Model
|
||||
|
||||
### 1. Storage Root
|
||||
|
||||
- each project owns `.studio/`;
|
||||
- new-project scaffolding creates that directory;
|
||||
- `.workspace/` is not the project-local Studio root for this model.
|
||||
|
||||
### 2. Activity Persistence
|
||||
|
||||
- shell activity is loaded when the project opens;
|
||||
- new activity is appended to that project's local history;
|
||||
- history is trimmed to the latest `500` entries.
|
||||
|
||||
### 3. Scope Rule
|
||||
|
||||
- project-local shell history belongs to the project;
|
||||
- launcher-global concerns remain outside this storage path;
|
||||
- future Studio project configuration can live under the same `.studio/` root.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Why activity cannot stay application-global
|
||||
|
||||
If two projects have one shared persisted feed, the shell stops teaching the user what happened in the currently opened project.
|
||||
That destroys causality instead of preserving it.
|
||||
|
||||
## Common Pitfalls and Anti-Patterns
|
||||
|
||||
- Treating project activity as if it were launcher-global state.
|
||||
- Mixing unrelated projects into one persisted activity history.
|
||||
- Leaving project-local Studio files in ad hoc roots instead of `.studio/`.
|
||||
- Letting unbounded activity persistence grow without a hard cap.
|
||||
|
||||
## References
|
||||
|
||||
- Specs:
|
||||
- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- Related learn:
|
||||
- [`./mental-model-studio-shell.md`](./mental-model-studio-shell.md)
|
||||
@ -1,71 +0,0 @@
|
||||
# PR-05a Assets Workspace Foundation and Service State
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the first executable slice of the `Assets` workspace based on:
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
This PR creates the workspace foundation, service-facing state model, and event wiring required by all later `Assets` workspace slices.
|
||||
|
||||
## Objective
|
||||
|
||||
Replace the current `WorkspaceId.ASSETS` placeholder with a concrete `AssetsWorkspace` foundation that can:
|
||||
|
||||
- boot inside the Studio shell,
|
||||
- request and refresh asset data from Studio-facing services,
|
||||
- maintain stable selection state,
|
||||
- surface loading/empty/error states,
|
||||
- and expose internal state in a way that later UI slices can reuse.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- existing Studio shell and event bus foundations
|
||||
- existing packer-facing Studio contracts and specifications
|
||||
|
||||
## Scope
|
||||
|
||||
- create a concrete `AssetsWorkspace`
|
||||
- define workspace-local view state models for:
|
||||
- navigator state
|
||||
- selected asset state
|
||||
- loading/error state
|
||||
- define service-facing DTO adapters needed by the workspace
|
||||
- define workspace event publications for asset refresh and selection updates
|
||||
- integrate the workspace into the existing shell/workspace switch flow
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final asset navigator visuals yet
|
||||
- no final preview rendering yet
|
||||
- no final staged mutation UI yet
|
||||
- no production-grade packer backend implementation if stubs or adapters are still required
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Replace the placeholder assets workspace with a concrete class and root layout.
|
||||
2. Introduce workspace-local state objects for navigator, selection, and detail hydration.
|
||||
3. Introduce a Studio-facing service boundary for loading asset collections and selected-asset details.
|
||||
4. Wire the workspace into `StudioWorkspaceEventBus` for refresh and selection lifecycle.
|
||||
5. Define stable loading, empty, no-results, and error states in code.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- selecting `Assets` opens a real workspace rather than a placeholder
|
||||
- the workspace can request asset data through a Studio service boundary
|
||||
- loading, empty, and error states are visible and distinct
|
||||
- selection state is modelled explicitly and can be preserved by identity
|
||||
- the workspace has enough state structure to support the later navigator and details PRs without redesign
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for workspace state transitions
|
||||
- unit tests for selection retention logic
|
||||
- UI smoke validation that the Assets workspace mounts cleanly in the shell
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio` workspace classes
|
||||
- Studio event wiring
|
||||
- Studio-facing asset service abstractions
|
||||
- tests for workspace state and selection behavior
|
||||
@ -1,72 +0,0 @@
|
||||
# PR-05b Asset Navigator Search Filters and Selection
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the left-side `Asset Tree` / `Asset Navigator` for the `Assets` workspace.
|
||||
|
||||
This PR applies the navigator and selection rules from:
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the first concrete asset navigator with:
|
||||
|
||||
- asset-first grouped navigation
|
||||
- semantic filters
|
||||
- textual search
|
||||
- stable single selection
|
||||
- explicit loading/empty/no-results/error states
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement the custom visual asset navigator control
|
||||
- render group nodes and asset nodes
|
||||
- implement baseline filters:
|
||||
- `Managed`
|
||||
- `Orphan`
|
||||
- `Diagnostics`
|
||||
- `Preload`
|
||||
- implement textual search over asset name and path context
|
||||
- preserve selection by `asset_id` or orphan root path as appropriate
|
||||
- allow optional expansion into asset inputs only as supporting inspection
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final selected-asset details composition yet
|
||||
- no final mutation staging UI yet
|
||||
- no heavy sorting or multi-select support
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Implement the navigator control and node rendering model.
|
||||
2. Add the baseline filters and search composition logic.
|
||||
3. Add stable selection reconciliation during refresh.
|
||||
4. Add explicit navigator states for loading, empty, no-results, and workspace error.
|
||||
5. Add the visual markers for managed/orphan, diagnostics, preload, and broad asset family.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the `Assets` workspace shows a real asset navigator on the left
|
||||
- assets are grouped by path-aware structure without degrading into a raw file tree
|
||||
- filters and search work together
|
||||
- selection remains stable across refresh when identity is preserved
|
||||
- orphan assets appear in the same navigator flow with clearly differentiated styling
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for filter/search composition
|
||||
- unit tests for selection preservation rules
|
||||
- UI smoke validation for node rendering and navigator states
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `AssetsWorkspace`
|
||||
- custom navigator controls
|
||||
- navigator view models
|
||||
- selection reconciliation logic
|
||||
- tests for filters, search, and selection behavior
|
||||
@ -1,80 +0,0 @@
|
||||
# PR-05c Selected Asset Details Contract and Preview
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the selected-asset details surface in the required fixed order:
|
||||
|
||||
1. `Summary`
|
||||
2. `Runtime Contract`
|
||||
3. `Inputs / Preview`
|
||||
4. `Diagnostics`
|
||||
5. `Actions`
|
||||
|
||||
This PR materializes the didactic core of the `Assets` workspace.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the first usable selected-asset details experience, including:
|
||||
|
||||
- summary identity/state rendering
|
||||
- runtime-facing contract rendering
|
||||
- inputs-by-role rendering
|
||||
- first previewable input surfaces
|
||||
- inline diagnostics
|
||||
- action groups with routine vs sensitive separation
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- [`./PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- render the fixed details skeleton
|
||||
- render summary metadata and location
|
||||
- render runtime contract fields such as `output.format`, `codec`, and `preload`
|
||||
- render input groups and input selection
|
||||
- implement first preview surfaces for previewable inputs
|
||||
- render inline diagnostics by severity
|
||||
- render action groups for:
|
||||
- `Doctor`
|
||||
- `Build`
|
||||
- `Adopt`
|
||||
- `Register`
|
||||
- sensitive operations placeholders where needed
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final staged preview/apply workflow yet
|
||||
- no final lower log integration yet
|
||||
- no exhaustive preview support for every asset family
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Build the selected-asset details layout in the mandated section order.
|
||||
2. Render summary and runtime contract from workspace state.
|
||||
3. Implement inputs-by-role rendering and input selection.
|
||||
4. Implement baseline preview handling for previewable types.
|
||||
5. Render inline diagnostics and action grouping.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- selecting an asset hydrates a full details view in the fixed section order
|
||||
- runtime-facing contract fields are visible without raw JSON inspection
|
||||
- previewable inputs can be inspected from the details area
|
||||
- diagnostics are visible inline and differentiated by severity
|
||||
- routine actions and sensitive actions are visibly separated
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for selected-asset detail mapping
|
||||
- unit tests for action availability by asset state
|
||||
- UI smoke validation for previewable input rendering
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `AssetsWorkspace` details area
|
||||
- preview components
|
||||
- diagnostics rendering
|
||||
- action surface wiring
|
||||
- tests for selected-asset detail behavior
|
||||
@ -1,63 +0,0 @@
|
||||
# PR-05d Assets Activity Progress and Logs Integration
|
||||
|
||||
## Briefing
|
||||
|
||||
Integrate the `Assets` workspace with Studio activity, progress, and logs according to the assets workspace specification.
|
||||
|
||||
## Objective
|
||||
|
||||
Make the `Assets` workspace operationally legible by wiring:
|
||||
|
||||
- structured activity into the shell right-side panel
|
||||
- contextual progress into the workspace
|
||||
- detailed textual logs into the lower region
|
||||
- failure retention and acknowledgement surfaces where required
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- map asset-service events into Studio activity entries
|
||||
- aggregate repetitive background events into user-facing summaries
|
||||
- wire `progress_updated` into progress surfaces without feed spam
|
||||
- expose lower-region textual logs for asset operations
|
||||
- retain recent actionable failures until acknowledgement
|
||||
- mirror selected-asset failures inline where applicable
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no generic all-workspace activity framework redesign beyond what Assets needs now
|
||||
- no final cross-workspace logs unification
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define asset-workspace activity mapping rules.
|
||||
2. Wire workspace and global bus publications for asset activity.
|
||||
3. Implement feed aggregation for repetitive events.
|
||||
4. Implement inline progress and lower-region logs integration.
|
||||
5. Retain and surface actionable failures across shell and workspace surfaces.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- asset events appear in the global `Activity` feed as user-oriented entries
|
||||
- progress updates do not spam the feed
|
||||
- logs are visible in the lower region for technical drill-down
|
||||
- actionable failures remain visible until acknowledged
|
||||
- selected-asset failures also appear inline when relevant
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for activity aggregation mapping
|
||||
- unit tests for failure retention logic
|
||||
- UI smoke validation for shell/workspace activity interplay
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- activity event adapters
|
||||
- progress surfaces
|
||||
- workspace log region integration
|
||||
- failure retention state
|
||||
- tests for activity mapping and failure behavior
|
||||
@ -1,75 +0,0 @@
|
||||
# PR-05e Assets Staged Mutations Preview and Apply
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the preview-first mutation flows for the `Assets` workspace.
|
||||
|
||||
This PR applies the staged mutation rules from:
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver inline staged mutation review for sensitive asset operations, including:
|
||||
|
||||
- preview generation
|
||||
- blockers, warnings, and safe-fix separation
|
||||
- registry vs workspace impact explanation
|
||||
- apply gating
|
||||
- activity integration for preview/apply lifecycle
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement inline staged review panel inside the `Assets` workspace
|
||||
- support preview-first handling for:
|
||||
- `Adopt`
|
||||
- `Forget`
|
||||
- `Remove`
|
||||
- `Quarantine`
|
||||
- relocational mutations
|
||||
- batch mutations when available
|
||||
- render proposed actions, blockers, warnings, safe fixes, and diff-style effects
|
||||
- disable `Apply` while blockers exist
|
||||
- use modal confirmation only for high-risk final commits
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no fully generic mutation framework for every Studio workspace
|
||||
- no speculative batch authoring flows that do not yet exist in services
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the staged review panel and its state model.
|
||||
2. Integrate preview requests and preview-ready responses from services.
|
||||
3. Render registry impact and workspace impact separately.
|
||||
4. Gate apply on blockers.
|
||||
5. Wire `preview_ready`, `action_applied`, and `action_failed` into activity.
|
||||
6. Add modal confirmation only where the final commit is high-risk.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- sensitive asset mutations do not execute directly from a single click
|
||||
- preview clearly shows what will change in registry and workspace
|
||||
- blockers prevent apply
|
||||
- safe fixes remain visually distinct from destructive actions
|
||||
- preview/apply lifecycle events surface correctly in workspace and activity
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for preview state mapping and apply gating
|
||||
- unit tests for registry/workspace impact rendering rules
|
||||
- UI smoke validation for staged mutation flows
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- staged review panel
|
||||
- asset mutation action wiring
|
||||
- preview/apply state models
|
||||
- activity integration for mutation lifecycle
|
||||
- tests for preview and apply behavior
|
||||
@ -1,111 +0,0 @@
|
||||
# PR-06 Project-Scoped Studio State and Activity Persistence
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Move Studio-local project persistence under each project root and make shell activity durable per project.
|
||||
|
||||
The target model is:
|
||||
|
||||
- each project owns a `.studio/` directory;
|
||||
- `.studio/` is created when a new project is created;
|
||||
- shell activity is stored inside that project-local directory and restored when the project is opened;
|
||||
- activity retention is capped at a fixed maximum of `500` entries;
|
||||
- the same `.studio/` root becomes the reserved home for future Studio project configuration.
|
||||
|
||||
## Objective
|
||||
|
||||
Make Studio state project-scoped instead of application-global where the data is inherently tied to one project, starting with activity persistence and the project-local Studio storage root.
|
||||
|
||||
After this change:
|
||||
|
||||
- opening a project reloads its recent activity feed;
|
||||
- new activity entries are appended to that project's persisted history;
|
||||
- persisted history is trimmed to the latest `500` entries;
|
||||
- newly created projects already contain the `.studio/` structure expected by Studio.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- current project creation flow in `ProjectCatalogService`
|
||||
- current shell activity mapping and rendering in `StudioActivityFeedControl`
|
||||
|
||||
## Scope
|
||||
|
||||
- define the project-local Studio storage convention under `.studio/`
|
||||
- persist shell activity entries per project
|
||||
- restore persisted activity when a project shell opens
|
||||
- enforce a hard retention cap of `500` entries
|
||||
- create `.studio/` during new-project scaffolding
|
||||
- reserve `.studio/` as the home for future project-local Studio settings
|
||||
- replace the current scaffolded `.workspace/` directory with `.studio/`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no redesign of activity event semantics or severity mapping
|
||||
- no cross-project merged activity history
|
||||
- no migration of global launcher data such as known projects
|
||||
- no broad persistence pass for every workspace in this PR
|
||||
- no attempt to define every future file that may live under `.studio/`
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the `.studio/` storage contract for Studio-owned project data.
|
||||
Proposed baseline layout:
|
||||
- `.studio/activities.json` for persisted shell activity history
|
||||
- `.studio/settings.json` reserved for project-local Studio configuration
|
||||
|
||||
2. Introduce a small project-local storage path abstraction.
|
||||
It should centralize resolution of `.studio/`, activity storage, and future settings storage from `ProjectReference.rootPath()`.
|
||||
|
||||
3. Add an activity persistence service/repository.
|
||||
Responsibilities:
|
||||
- load persisted entries for a project;
|
||||
- store entries after append;
|
||||
- normalize malformed or missing files into an empty history;
|
||||
- trim persisted and in-memory history to the latest `500` records.
|
||||
|
||||
4. Refactor `StudioActivityFeedControl` to become project-aware at construction time.
|
||||
The control should:
|
||||
- hydrate its initial list from persisted project activity;
|
||||
- append new mapped entries to memory and persistence;
|
||||
- preserve the existing duplicate-suppression behavior unless it conflicts with durable history expectations.
|
||||
|
||||
5. Update shell composition to pass the active `ProjectReference` into the activity feed.
|
||||
`MainView` should instantiate the feed for the currently opened project instead of a project-agnostic global feed.
|
||||
|
||||
6. Update project creation scaffolding.
|
||||
`ProjectCatalogService.createProject(...)` must create `.studio/` and stop creating `.workspace/`.
|
||||
If needed, opening an older project may lazily create `.studio/` on first persistence write.
|
||||
|
||||
7. Propagate the contract to Studio specs and tests.
|
||||
The shell spec should state that shell activity is project-scoped, restored on open, and retained with a bounded history.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- opening a project with an existing `.studio/activities.json` restores that project's recent activity feed before new events arrive
|
||||
- activity produced while a project is open is persisted under that project's `.studio/` directory
|
||||
- persisted activity history never exceeds `500` entries
|
||||
- newly created projects contain `.studio/`
|
||||
- new-project tests no longer expect `.workspace/`
|
||||
- opening a project without `.studio/activities.json` still works and initializes an empty feed
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for project scaffolding asserting `.studio/` creation
|
||||
- unit tests for activity storage load/save behavior
|
||||
- unit tests for retention trimming to `500`
|
||||
- unit tests for activity-feed hydration from persisted entries
|
||||
- unit tests for malformed or missing activity storage fallback
|
||||
- smoke validation opening two different projects and confirming isolated activity histories
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/projects/ProjectCatalogService.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/controls/shell/StudioActivityFeedControl.java`
|
||||
- new Studio project-storage service/repository classes under `prometeu-studio/src/main/java/p/studio/...`
|
||||
- `prometeu-studio/src/test/java/p/studio/projects/ProjectCatalogServiceTest.java`
|
||||
- new activity persistence tests under `prometeu-studio/src/test/java/p/studio/...`
|
||||
- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`
|
||||
@ -1,124 +0,0 @@
|
||||
# PR-07a Assets Event Topology and Lifecycle Foundation
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Refactor the `Assets` workspace foundation away from a monolithic `AssetWorkspace` that redraws major regions after local changes.
|
||||
|
||||
This slice establishes the corrective architectural direction for the Studio as a whole.
|
||||
|
||||
`Assets` is the first consumer and proving ground, but the target is not an `Assets`-only pattern.
|
||||
|
||||
The Studio-standard direction is:
|
||||
|
||||
- lifecycle-aware UI components;
|
||||
- typed workspace events as the update mechanism;
|
||||
- component-scoped subscriptions;
|
||||
- explicit separation between structural workspace sync and local UI projection updates;
|
||||
- reusable workspace framework pieces that other Studio workspaces must consume instead of inventing their own refresh-heavy flow.
|
||||
|
||||
## Objective
|
||||
|
||||
Create the event-driven workspace foundation required for all later `Assets` refactor slices and establish it as the correct Studio-wide pattern for workspace implementation.
|
||||
|
||||
After this PR:
|
||||
|
||||
- the workspace root coordinates composition instead of owning every region render path;
|
||||
- navigator, row, details, and details-internal controls can subscribe independently;
|
||||
- the workspace event bus becomes the primary update path for UI change propagation;
|
||||
- `refresh()` is no longer the default answer for local state changes.
|
||||
- the extracted lifecycle/event-driven primitives are designed for reuse by non-`Assets` workspaces.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- existing `StudioWorkspaceEventBus`
|
||||
- existing `StudioControlLifecycle` support
|
||||
|
||||
## Scope
|
||||
|
||||
- define the target event topology for the `Assets` workspace
|
||||
- define the target event topology as the canonical Studio workspace model
|
||||
- split workspace responsibilities between composition, state coordination, and component rendering
|
||||
- extract reusable workspace framework primitives where the abstraction is already justified by the `Assets` refactor
|
||||
- introduce lifecycle-aware component boundaries for:
|
||||
- navigator host
|
||||
- asset-list host
|
||||
- asset-row item
|
||||
- details host
|
||||
- details-local sections/forms
|
||||
- introduce reusable patterns or base components for:
|
||||
- workspace composition roots
|
||||
- lifecycle-managed event subscribers
|
||||
- projection host controls
|
||||
- structural-sync versus local-patch orchestration
|
||||
- define typed events for:
|
||||
- structural snapshot changes
|
||||
- projection changes
|
||||
- selection changes
|
||||
- selected-asset details lifecycle
|
||||
- local patch propagation
|
||||
- demote global redraw events to transitional or removable status
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final navigator visuals redesign in this slice
|
||||
- no final details-panel redesign in this slice
|
||||
- no mutation-semantics redesign beyond event routing needs
|
||||
- no broad shell-level event-system rewrite outside `Assets`
|
||||
- no fake generalization disconnected from concrete `Assets` usage
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the component tree and ownership model.
|
||||
The workspace root should compose controls and services, not render every region inline.
|
||||
|
||||
2. Introduce event contracts for the asset workspace projection model.
|
||||
The baseline contract should distinguish:
|
||||
- structural workspace sync events
|
||||
- navigator projection events
|
||||
- selected-asset details events
|
||||
- per-asset patch events
|
||||
|
||||
3. Convert `AssetWorkspace` into a composition root plus orchestration layer.
|
||||
It may still coordinate service calls, but rendering responsibilities should move into dedicated controls.
|
||||
|
||||
4. Extract reusable workspace-framework pieces while doing the refactor.
|
||||
`Assets` should consume the same primitives that future Studio workspaces are expected to consume.
|
||||
|
||||
5. Require lifecycle installation for event-consuming controls.
|
||||
Every component that subscribes to workspace events must implement `StudioControlLifecycle` and subscribe only while attached to the scene.
|
||||
|
||||
6. Mark the existing redraw-request pattern as transitional.
|
||||
`StudioAssetsNavigatorRedrawRequestedEvent` and `StudioAssetsDetailsRedrawRequestedEvent` should no longer be the target architecture.
|
||||
|
||||
7. Propagate the rule to Studio documentation.
|
||||
The resulting plans/spec updates should make clear that future workspaces are expected to build on this framework instead of introducing workspace-local refresh architecture.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the refactor has a clear component topology instead of one render-heavy workspace class
|
||||
- lifecycle-aware controls own their own subscriptions
|
||||
- the workspace event bus carries typed update events that components can consume independently
|
||||
- local UI changes can be expressed without a full workspace refresh path
|
||||
- the old redraw-request events are either removed or isolated behind temporary compatibility adapters
|
||||
- the extracted primitives are reusable by other Studio workspaces
|
||||
- the plan explicitly establishes this direction as the Studio-standard workspace architecture
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for event routing between composition root and child controls
|
||||
- unit tests for lifecycle subscribe/unsubscribe behavior on workspace controls
|
||||
- smoke validation that mounting and unmounting the workspace does not leak subscriptions
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- new reusable workspace-framework classes under `prometeu-studio/src/main/java/p/studio/...`
|
||||
- new `Assets` workspace controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`
|
||||
- `docs/studio/specs/3. Studio Components Module Specification.md`
|
||||
- tests for workspace event topology and lifecycle behavior
|
||||
@ -1,75 +0,0 @@
|
||||
# PR-07b Asset Navigator and Row Subscriptions
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Refactor the navigator side of the `Assets` workspace so the list and each asset row update through event subscriptions instead of workspace-wide rerendering.
|
||||
|
||||
## Objective
|
||||
|
||||
Make navigator behavior event-directed and component-local.
|
||||
|
||||
After this PR:
|
||||
|
||||
- the navigator list subscribes to projection changes it actually needs;
|
||||
- each asset row subscribes to row-scoped summary/selection updates;
|
||||
- search and filters change the navigator projection without rebuilding the whole workspace;
|
||||
- selection styling and row patching happen without forcing a full list refresh from the workspace root.
|
||||
- the navigator and row patterns are implemented in a way that other Studio workspaces can reuse for list/detail navigation surfaces.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- extract the navigator into dedicated controls
|
||||
- separate navigator projection calculation from visual control ownership
|
||||
- introduce row-scoped subscriptions and row identity handling
|
||||
- keep reusable list/projection primitives outside `Assets`-only naming where they are genuinely cross-workspace
|
||||
- publish projection updates for:
|
||||
- search changes
|
||||
- filter changes
|
||||
- structural asset collection changes
|
||||
- per-asset summary patches
|
||||
- selection changes
|
||||
- remove direct row bookkeeping from the workspace root where possible
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no details-panel refactor in this slice
|
||||
- no final mutation confirmation flow refactor in this slice
|
||||
- no broad service-layer redesign beyond what navigator subscriptions require
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce an `AssetNavigatorControl` or equivalent host with lifecycle-managed subscriptions.
|
||||
2. Extract row rendering into an `AssetRowControl` or equivalent lifecycle-managed component.
|
||||
3. Move search/filter handling to event publication plus projection recalculation.
|
||||
4. Publish selection updates as typed events that row controls can consume directly.
|
||||
5. Replace root-owned row maps and manual selection restyling with row-scoped update flow.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- asset rows are no longer rebuilt by default on every local navigator change
|
||||
- search and filter changes update the navigator projection only
|
||||
- selecting an asset updates only the controls that depend on selection
|
||||
- patching one asset summary updates the affected row without requiring a full workspace reload
|
||||
- navigator controls subscribe and unsubscribe through the lifecycle support
|
||||
- reusable navigator/list subscription patterns are left available for future Studio workspaces
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for navigator projection event flow
|
||||
- unit tests for row identity stability across patches
|
||||
- unit tests for selection update behavior without full projection rebuild
|
||||
- UI smoke validation for search, filters, and selection transitions
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- new navigator and row controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- tests for navigator projection and row update behavior
|
||||
@ -1,82 +0,0 @@
|
||||
# PR-07c Asset Details and Form Lifecycle
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Refactor the selected-asset details side so the details host and its internal sections/forms subscribe only to the state they need.
|
||||
|
||||
This slice explicitly covers the problem called out in the current direction:
|
||||
|
||||
- the selected-asset details host must not own all redraws;
|
||||
- each internal section/form must update from events instead of full details rebuilds.
|
||||
|
||||
## Objective
|
||||
|
||||
Make the details area componentized, lifecycle-aware, and event-driven.
|
||||
|
||||
After this PR:
|
||||
|
||||
- summary/actions, runtime contract, inputs/preview, diagnostics, and mutation-preview sections can update independently;
|
||||
- details load state, ready state, and error state are event-driven;
|
||||
- local form interactions such as preload toggles or preview selection do not rebuild unrelated details content;
|
||||
- internal controls subscribe only while mounted.
|
||||
- the details-section and form-subscription patterns become reusable Studio workspace primitives where appropriate.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- extract the details host into dedicated controls
|
||||
- split details content into lifecycle-aware sections
|
||||
- extract reusable section-host and form-event patterns when they are not asset-specific
|
||||
- define details events for:
|
||||
- details loading started
|
||||
- details ready
|
||||
- details failed
|
||||
- local summary patch applied
|
||||
- preview input changed
|
||||
- preview zoom changed
|
||||
- mutation preview state changed
|
||||
- route details-local form actions through the workspace bus instead of root-owned imperative redraw
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no navigator refactor in this slice
|
||||
- no shell activity redesign in this slice
|
||||
- no cross-workspace form framework extraction unless needed by the `Assets` details controls
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce a dedicated details host control with lifecycle-managed subscriptions.
|
||||
2. Extract stable details sections into separate controls.
|
||||
3. Move details load and error transitions to typed events.
|
||||
4. Route details-local interactions through narrow events and local state holders.
|
||||
5. Remove root-level details reconstruction for interactions that affect only one section.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the selected-asset details view is no longer rebuilt as one large region for section-local changes
|
||||
- forms and preview controls update independently
|
||||
- details-ready and details-error transitions are observable through typed events
|
||||
- details-local subscriptions are owned by the mounted controls, not the workspace root
|
||||
- changing one local control does not force unrelated details sections to rerender
|
||||
- reusable details/form lifecycle patterns are available for future Studio workspaces
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for details lifecycle event flow
|
||||
- unit tests for section-local updates
|
||||
- unit tests for preload-toggle or equivalent form patch behavior
|
||||
- UI smoke validation for selection, details loading, preview interaction, and diagnostics visibility
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- new details controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- tests for details load state and section-local updates
|
||||
@ -1,83 +0,0 @@
|
||||
# PR-07d Asset Mutation and Structural Sync Orchestration
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Replace the current mutation flow that falls back to `refresh()` after many operations with an event-directed orchestration model.
|
||||
|
||||
The key rule is:
|
||||
|
||||
- local patches stay local;
|
||||
- only structural workspace changes trigger structural sync;
|
||||
- structural sync is explicit and typed, not an incidental rerender path.
|
||||
|
||||
## Objective
|
||||
|
||||
Make asset operations compatible with the event-driven component model.
|
||||
|
||||
After this PR:
|
||||
|
||||
- direct mutations publish patch or structural-sync events according to their actual impact;
|
||||
- row and details controls react to targeted operation results when possible;
|
||||
- create/remove/relocate or other structural operations request a workspace sync explicitly;
|
||||
- the workspace no longer treats every successful operation as a reason to reload everything.
|
||||
- the local-patch versus structural-sync rule is available as a reusable Studio workspace orchestration rule.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- classify operations by update impact:
|
||||
- local summary patch
|
||||
- details patch
|
||||
- structural workspace sync
|
||||
- failure retention/reporting
|
||||
- extract reusable orchestration helpers or contracts where the distinction is cross-workspace rather than asset-specific
|
||||
- route mutation preview/apply results through typed events
|
||||
- replace generic `refresh()` fallbacks for non-structural success paths
|
||||
- keep progress/log/activity integration aligned with the new orchestration path
|
||||
- make structural sync requests explicit and testable
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no redesign of packer service semantics
|
||||
- no generic Studio-wide command bus abstraction in this slice
|
||||
- no persistence work unrelated to asset-workspace orchestration
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define operation-result events and structural-sync request events.
|
||||
2. Map each mutation action to its update strategy.
|
||||
3. Update mutation flows to publish events instead of directly forcing global workspace refresh.
|
||||
4. Keep structural reload only for actions that truly change collection shape or asset identity.
|
||||
5. Wire progress, logs, and activity to the new operation flow without reintroducing redraw coupling.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- include/exclude, preload, and similar local operations can update via targeted events
|
||||
- create/register/remove/relocate use explicit structural-sync flow only when required
|
||||
- mutation preview and apply flows do not directly rebuild navigator and details by default
|
||||
- activity/log/progress signals remain correct under the new orchestration
|
||||
- the remaining structural sync path is narrow, explicit, and justified by actual data-shape changes
|
||||
- the orchestration rule is documented as reusable Studio behavior, not an `Assets` exception
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for operation-to-update-strategy mapping
|
||||
- unit tests for structural-sync event publication
|
||||
- unit tests for targeted patch propagation after successful operations
|
||||
- UI smoke validation for register/include/exclude/relocate/remove flows
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- mutation and orchestration classes under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- tests for mutation orchestration and structural sync behavior
|
||||
@ -1,74 +0,0 @@
|
||||
# PR-07e Assets Refactor Cleanup and Regression Coverage
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Consolidate the refactor by removing obsolete redraw-heavy code paths, tightening naming, and locking the event-driven behavior with tests.
|
||||
|
||||
## Objective
|
||||
|
||||
Finish the corrective refactor so the codebase does not drift back toward monolithic render ownership.
|
||||
|
||||
After this PR:
|
||||
|
||||
- obsolete redraw-request and monolithic render helpers are removed;
|
||||
- remaining component boundaries are clearer and easier to maintain;
|
||||
- tests guard lifecycle, event routing, and selective-update behavior;
|
||||
- the workspace code is organized around durable responsibilities rather than incremental leftovers.
|
||||
- the resulting framework is left in a shape that other Studio workspaces can adopt directly.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- remove dead or transitional redraw-oriented code
|
||||
- rename classes/events where the old naming reflects the wrong direction
|
||||
- tighten package structure for navigator, details, and orchestration code
|
||||
- make reusable framework pieces visible and discoverable to future workspace implementations
|
||||
- add regression coverage for:
|
||||
- lifecycle subscription hygiene
|
||||
- selection propagation
|
||||
- row patch propagation
|
||||
- details-local updates
|
||||
- structural sync boundaries
|
||||
- update Studio learn/spec material if the refactor exposes terminology drift
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no new user-facing asset features in this slice
|
||||
- no speculative refactor outside the `Assets` workspace and its direct event contracts
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Remove compatibility layers that existed only to bridge from the old refresh-heavy implementation.
|
||||
2. Normalize class and event naming around lifecycle and event-driven ownership.
|
||||
3. Reorganize tests to reflect component boundaries instead of one giant workspace class.
|
||||
4. Update documentation to reflect the stabilized architecture.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the refactored `Assets` workspace no longer depends on redraw-request events as a primary mechanism
|
||||
- code ownership is split along navigator, details, and orchestration boundaries
|
||||
- lifecycle and event-driven behavior are covered by focused tests
|
||||
- the remaining `AssetWorkspace` root is materially smaller and primarily compositional
|
||||
- the reusable framework surface is clear enough for other workspaces to consume instead of cloning `Assets` internals
|
||||
|
||||
## Validation
|
||||
|
||||
- full unit-test pass for asset-workspace packages
|
||||
- targeted regression tests for mount/unmount lifecycle safety
|
||||
- targeted regression tests proving that local updates stay local unless structural sync is requested
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/...`
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
||||
- `docs/studio/learn/mental-model-assets-workspace.md`
|
||||
@ -1,117 +0,0 @@
|
||||
# PR-08 Assets Workspace Panel Package Boundaries and Local Subscriptions
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
The current `Assets` workspace still keeps too much control logic concentrated in top-level workspace-area classes.
|
||||
|
||||
That leaves package boundaries flatter than they should be and still weakens the intended Studio model:
|
||||
|
||||
- every panel should own its own workspace-bus subscriptions;
|
||||
- `AssetWorkspace` should stay as composition root and orchestration layer;
|
||||
- the asset list should live in its own package area;
|
||||
- the full right-hand details side should be split into package-owned panels with direct lifecycle-managed subscriptions.
|
||||
|
||||
This refactor is a structural follow-up to the `PR-07` family.
|
||||
|
||||
It does not redefine the event-driven direction; it completes it by enforcing package topology and subscription ownership at the panel level.
|
||||
|
||||
## Objective
|
||||
|
||||
Reorganize the `Assets` workspace into explicit package areas so that every list or details panel consumes the workspace event bus directly and subscribes only to the state it needs.
|
||||
|
||||
After this PR:
|
||||
|
||||
- `AssetWorkspace` composes package-scoped controls instead of hosting panel logic directly;
|
||||
- all asset-list controls live under an `asset list` package area;
|
||||
- the right-hand details side is organized under `details/...` package areas;
|
||||
- `summary`, `actions`, `contract`, `preview`, and `diagnostics` each manage their own subscriptions;
|
||||
- the package layout itself teaches the correct Studio workspace architecture.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-07e-assets-refactor-cleanup-and-regression-coverage.md`](./PR-07e-assets-refactor-cleanup-and-regression-coverage.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- create an `asset list` package area under the `Assets` workspace implementation
|
||||
- move the asset-list host and asset-list item control into that package area
|
||||
- require both asset-list host and asset-list item to receive `StudioWorkspaceEventBus`
|
||||
- require both asset-list host and asset-list item to own their own lifecycle-managed subscriptions
|
||||
- create a `details` package area for the full right-hand side of the workspace
|
||||
- split details internals into package-owned subareas such as:
|
||||
- `details/summary`
|
||||
- `details/actions`
|
||||
- `details/contract`
|
||||
- `details/preview`
|
||||
- `details/diagnostics`
|
||||
- require each details panel to subscribe directly to the event stream it consumes
|
||||
- reduce coordinator-style pass-through logic where a child panel can consume the workspace bus directly
|
||||
- keep shared details support code only where it removes real duplication without re-centralizing subscriptions
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no new mutation semantics
|
||||
- no new global event-bus abstraction
|
||||
- no visual redesign of the workspace
|
||||
- no cross-workspace extraction unless a primitive is already justified by this refactor
|
||||
- no return to top-level refresh orchestration as the normal update model
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the target package topology.
|
||||
The package tree should reflect workspace areas, not arbitrary implementation convenience.
|
||||
|
||||
2. Move asset-list code into a dedicated package area.
|
||||
The list host and list item should be colocated and should consume the workspace bus directly.
|
||||
|
||||
3. Normalize asset-list subscriptions.
|
||||
The asset-list host should subscribe to list-level projection state.
|
||||
The asset-list item should subscribe to item-local concerns such as selection and asset patch events.
|
||||
|
||||
4. Move the full right-hand details side into a dedicated `details` package area.
|
||||
The top-level details host should stay thin and should mount panel controls by workspace area.
|
||||
|
||||
5. Split details panels by concern.
|
||||
`summary`, `actions`, `contract`, `preview`, and `diagnostics` should each live in package-owned subareas and subscribe for themselves.
|
||||
|
||||
6. Remove parent-owned update routing where it is only forwarding state to children.
|
||||
If a child panel can subscribe to the workspace bus safely, it should do so directly.
|
||||
|
||||
7. Re-check constructor contracts.
|
||||
Every event-consuming panel should receive the `StudioWorkspaceEventBus` explicitly, plus only the interaction ports it truly needs.
|
||||
|
||||
8. Clean naming and file layout.
|
||||
Class names, package names, and placement should make the `Assets` workspace structure obvious to a new maintainer.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- there is a dedicated package area for the asset list inside the `Assets` workspace
|
||||
- asset-list host and asset-list item both receive `StudioWorkspaceEventBus`
|
||||
- asset-list host and asset-list item both subscribe directly to the events they need
|
||||
- there is a dedicated `details` package area for the right-hand workspace side
|
||||
- `summary`, `actions`, `contract`, `preview`, and `diagnostics` each live in their own package-owned area
|
||||
- each details panel owns its own lifecycle-managed subscriptions
|
||||
- `AssetWorkspace` no longer acts as the effective subscriber for panel-internal state
|
||||
- package structure and constructor boundaries make the lifecycle model explicit
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for lifecycle subscribe/unsubscribe on moved controls
|
||||
- unit tests or focused integration tests proving list item and details panels react from their own subscriptions
|
||||
- regression validation that asset selection and local patch flows still update without workspace-wide refresh
|
||||
- package-level review that no event-consuming panel is left without direct bus access
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` moved into list/details package areas
|
||||
- asset-list controls under a dedicated list package
|
||||
- details controls under `details/...` packages
|
||||
- tests for workspace lifecycle and subscription ownership
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md` if package/lifecycle wording needs tightening after the refactor
|
||||
@ -1,164 +0,0 @@
|
||||
# PR-09 Asset Move Action and Relocate Wizard
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Adicionar a action `Move` na área de actions do asset selecionado e conectá-la a um wizard de relocação explícita.
|
||||
|
||||
O usuário deve escolher o destino do asset e revisar um resumo antes da execução.
|
||||
Depois da confirmação, o Studio não move diretórios localmente.
|
||||
Ele apenas envia um comando de relocação para o packer, que passa a ser o owner completo da mudança:
|
||||
|
||||
- atualiza o estado interno necessário;
|
||||
- move o diretório do asset dentro da árvore `assets` do projeto;
|
||||
- emite eventos operacionais até a conclusão.
|
||||
|
||||
Este plano também fecha uma regra operacional que precisa existir nas duas pontas:
|
||||
|
||||
- o diretório destino final do asset não pode já ser um root de asset;
|
||||
- portanto, o root destino não pode conter `asset.json`.
|
||||
|
||||
Após a confirmação do resumo, o modal deve entrar em estado de espera com spinner, escutando o evento operacional do packer.
|
||||
Quando a operação terminar:
|
||||
|
||||
- sucesso: o Studio dispara refresh, fecha o modal e reposiciona a seleção;
|
||||
- falha: o modal sai do estado de espera e mostra a falha sem fechar silenciosamente.
|
||||
|
||||
## Objective
|
||||
|
||||
Entregar um fluxo de `Move` que seja explícito, previsível e compatível com o modelo em que o packer executa a mutação real e o Studio apenas comanda e observa.
|
||||
|
||||
Após este PR:
|
||||
|
||||
- a seção `Actions` do selected asset expõe `Move`;
|
||||
- clicar em `Move` abre um wizard dedicado;
|
||||
- o wizard coleta o parent de destino e o nome final do diretório;
|
||||
- o wizard mostra um passo final de resumo antes do comando final;
|
||||
- o Studio não aceita um destino cujo root já contenha `asset.json`;
|
||||
- o packer também rejeita esse destino como regra de segurança e conformance;
|
||||
- a confirmação final envia um comando de relocation para o packer via API;
|
||||
- o modal entra em espera com spinner até receber o evento terminal da operação;
|
||||
- o refresh estrutural só ocorre depois do evento de conclusão do packer.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
- cross-domain reference: [`../../packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](../../packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md)
|
||||
- cross-domain reference: [`../../packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md`](../../packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- adicionar a action `Move` na seção `Actions` do details
|
||||
- introduzir um `Relocate Wizard` efetivamente utilizável pelo selected asset atual
|
||||
- coletar destino por:
|
||||
- parent directory
|
||||
- destination name
|
||||
- target root derivado
|
||||
- mostrar passo final de resumo antes da confirmação
|
||||
- enviar um comando `RELOCATE_ASSET` com `targetRoot` explícito para o packer
|
||||
- abrir estado modal de espera com spinner após confirmação
|
||||
- correlacionar a operação via `operationId`
|
||||
- escutar o evento operacional do packer até `ACTION_APPLIED` ou `ACTION_FAILED`
|
||||
- publicar structural sync explícito apenas após conclusão bem-sucedida
|
||||
- validar no Studio que `targetRoot/asset.json` não exista
|
||||
- validar no packer que `targetRoot/asset.json` não exista, mesmo se o Studio falhar em bloquear antes
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- não redesenhar o mutation preview panel inteiro
|
||||
- não introduzir rename inline fora do wizard
|
||||
- não adicionar batch move
|
||||
- não redefinir semântica de identidade do asset
|
||||
- não permitir fallback para target automático quando o usuário iniciou `Move`
|
||||
- não mover diretórios diretamente pelo Studio fora do comando ao packer
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Expor `Move` na seção `Actions`.
|
||||
O botão deve existir apenas quando houver asset selecionado e deve abrir o wizard a partir do `AssetReference` atual.
|
||||
|
||||
2. Implementar o wizard de relocação como fluxo explícito de destino.
|
||||
O wizard deve reutilizar a linguagem já existente de `relocateWizard` e coletar:
|
||||
- root atual
|
||||
- diretório parent de destino
|
||||
- nome final do diretório
|
||||
- target root calculado
|
||||
|
||||
3. Adicionar validação local de destino.
|
||||
O wizard deve bloquear avanço/confirmação quando:
|
||||
- o target root for igual ao root atual;
|
||||
- o target root sair da área válida esperada;
|
||||
- o target root já contiver `asset.json`.
|
||||
|
||||
4. Adicionar passo final de resumo.
|
||||
Antes do comando final, o usuário deve ver um resumo do:
|
||||
- asset atual
|
||||
- root atual
|
||||
- parent de destino
|
||||
- nome final
|
||||
- target root resultante
|
||||
|
||||
5. Integrar o wizard ao fluxo de comando assíncrono do packer.
|
||||
A saída do wizard deve virar `PackerMutationRequest(RELOCATE_ASSET, ..., targetRoot)`, sem usar target automático.
|
||||
Depois do `OK`, o Studio inicia a operação, captura o `operationId` retornado e coloca o modal em estado de espera.
|
||||
|
||||
6. Esperar conclusão por evento, não por refresh cego.
|
||||
O modal deve escutar `StudioPackerOperationEvent` correlacionado por `operationId`.
|
||||
Regras:
|
||||
- `ACTION_APPLIED`: disparar refresh estrutural, fechar modal e reselecionar o asset relocado;
|
||||
- `ACTION_FAILED`: sair do spinner, manter modal aberto e mostrar a falha;
|
||||
- eventos intermediários como `PROGRESS_UPDATED` podem atualizar a mensagem/estado visual, mas não fecham o modal.
|
||||
|
||||
7. Endurecer a regra no packer.
|
||||
O preview/apply de relocation deve recusar destino cujo root já contenha `asset.json`, produzindo blocker claro e estável.
|
||||
|
||||
8. Orquestrar o pós-conclusão como mudança estrutural.
|
||||
Relocation bem-sucedida deve acionar sync estrutural explícito e reposicionar a seleção para o asset movido no novo root.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `Move` aparece na seção `Actions` do asset selecionado
|
||||
- clicar em `Move` abre wizard dedicado em vez de mutação imediata
|
||||
- o wizard exige destino explícito escolhido pelo usuário
|
||||
- existe passo final de resumo antes da conclusão
|
||||
- `targetRoot/asset.json` bloqueia o fluxo já no Studio
|
||||
- o packer também bloqueia `targetRoot/asset.json` como regra de segurança
|
||||
- o `OK` final envia o comando ao packer e coloca o modal em espera com spinner
|
||||
- o modal só fecha depois de `ACTION_APPLIED` para a mesma operação
|
||||
- falha operacional não fecha o modal silenciosamente
|
||||
- sucesso operacional executa structural sync explícito
|
||||
- a seleção final aponta para o asset já movido, não para o root antigo
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests para validação de target root no wizard
|
||||
- unit tests para derivação de `targetRoot` a partir de parent + destination name
|
||||
- unit tests para correlação `operationId -> modal state`
|
||||
- unit tests para sucesso/falha dirigidos por `StudioPackerOperationEvent`
|
||||
- unit tests para publication/orchestration de relocation como structural sync
|
||||
- packer tests para blocker quando `targetRoot/asset.json` já existe
|
||||
- smoke test de UI para:
|
||||
- abrir `Move`
|
||||
- editar destino
|
||||
- ver resumo final
|
||||
- bloquear destino inválido
|
||||
- confirmar operação
|
||||
- ver spinner de espera
|
||||
- fechar no evento de sucesso
|
||||
- manter aberto no evento de falha
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md` se a regra de destino inválido precisar ser tornada mais explícita
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/actions/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` mutation orchestration wiring
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `prometeu-studio/src/main/resources/i18n/messages.properties`
|
||||
- `prometeu-packer/src/main/java/p/packer/mutations/...`
|
||||
- testes de Studio para wizard/flow
|
||||
- testes de packer para relocation target validation
|
||||
@ -1,81 +0,0 @@
|
||||
# PR-10a Bank Composition Details DTO Projection
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
Cross-domain impact: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Introduce the Studio-owned DTO projection boundary for `Bank Composition` inside `Asset Details`.
|
||||
|
||||
This slice converts runtime/details source data into section-facing DTOs before any new section UI or middleware is added.
|
||||
|
||||
The goal is to land the data boundary first, so the UI work that follows does not bind directly to snapshot rows or raw `asset.json` shapes.
|
||||
|
||||
## Objective
|
||||
|
||||
After this PR:
|
||||
|
||||
- `Asset Details` has a Studio-owned DTO family for `Bank Composition`;
|
||||
- snapshot-derived data feeds `available` rows;
|
||||
- persisted selection data feeds `selected` rows;
|
||||
- only non-blocking files reach the `available` DTO list;
|
||||
- selected ordering is represented in a way that can later map to explicit persisted indexes.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Bank Composition Details DTO Projection Decision.md`](../decisions/Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add the Studio DTO family for bank-composition rows and section data
|
||||
- map details/snapshot source data into:
|
||||
- `available`
|
||||
- `selected`
|
||||
- start the DTO field set with:
|
||||
- `path`
|
||||
- `displayName`
|
||||
- `size`
|
||||
- `lastModified`
|
||||
- `fingerprint`
|
||||
- `metadata`
|
||||
- filter blocking files out of the `available` projection
|
||||
- ensure selected ordering is available to the UI as ordered row state
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no new section UI yet
|
||||
- no dual-list component yet
|
||||
- no capacity meter yet
|
||||
- no staged-edit coordinator yet
|
||||
- no persistence/apply integration yet
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce the DTO types for bank-composition details data.
|
||||
2. Extend the details projection path to populate `available` and `selected`.
|
||||
3. Filter blocking files before DTO emission.
|
||||
4. Preserve selected ordering in the section-facing projection.
|
||||
5. Add regression tests around DTO mapping and filtering.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `Asset Details` can provide Studio-owned `Bank Composition` DTOs without exposing raw packer internals to the section
|
||||
- `available` rows come from current runtime/details data
|
||||
- blocking files do not appear in `available`
|
||||
- `selected` rows are available as ordered data
|
||||
- the new DTO projection is ready for subsequent section and component slices
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for DTO mapping from details/snapshot source data
|
||||
- unit tests for blocking-file exclusion
|
||||
- unit tests for selected-row ordering preservation
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/...`
|
||||
- tests for details projection and DTO mapping
|
||||
- cross-domain touchpoint: packer-facing details DTO shaping if source data is still missing
|
||||
@ -1,75 +0,0 @@
|
||||
# PR-10b Bank Composition Base Components
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Introduce the base UI building blocks for `Bank Composition`:
|
||||
|
||||
- `StudioDualListView<T>`
|
||||
- `StudioAssetCapacityMeter`
|
||||
|
||||
This slice lands the named components with intentionally narrow first-wave APIs, before section-shell wiring or behavior orchestration.
|
||||
|
||||
## Objective
|
||||
|
||||
After this PR:
|
||||
|
||||
- `StudioDualListView<T>` exists as an abstract Studio component;
|
||||
- the first asset-details concrete dual-list implementation exists;
|
||||
- `StudioAssetCapacityMeter` exists as a dumb vertical meter component;
|
||||
- right-list ordering support includes `moveUp`, `moveDown`, and visible indices.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Bank Composition Base Components Decision.md`](../decisions/Bank%20Composition%20Base%20Components%20Decision.md)
|
||||
- [`../decisions/Bank Composition Details DTO Projection Decision.md`](../decisions/Bank%20Composition%20Details%20DTO%20Projection%20Decision.md)
|
||||
- [`./PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add abstract `StudioDualListView<T>`
|
||||
- add the first asset-details-specific concrete dual-list implementation
|
||||
- add dumb `StudioAssetCapacityMeter`
|
||||
- support row rendering directly in the concrete dual-list implementation
|
||||
- support right-list index display
|
||||
- support `moveUp` and `moveDown` affordances in the component contract
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no section shell yet
|
||||
- no `FormSession` integration yet
|
||||
- no family-specific capacity rules inside components
|
||||
- no workspace-bus contract yet
|
||||
- no apply persistence
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add the abstract dual-list base component.
|
||||
2. Add the first concrete asset-details implementation against the new DTOs.
|
||||
3. Add the capacity meter component with:
|
||||
- `progress`
|
||||
- label
|
||||
- severity band
|
||||
- optional hint text
|
||||
4. Add component tests for rendering, ordering affordances, and meter state display.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the codebase contains the new named base components for `Bank Composition`
|
||||
- the first concrete dual-list implementation works against Studio DTOs
|
||||
- the right/build list can show visible indices
|
||||
- the component contract exposes `moveUp` and `moveDown`
|
||||
- the capacity meter can render absolute progress and severity state without owning bank rules
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for dual-list rendering and ordering controls
|
||||
- unit tests for visible index updates
|
||||
- unit tests for capacity-meter state rendering
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/controls/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
|
||||
- tests for dual-list and capacity meter components
|
||||
@ -1,70 +0,0 @@
|
||||
# PR-10c Bank Composition Section Shell and Form Session Integration
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Add the `Bank Composition` section shell into `Asset Details`, aligned with `Runtime Contract` and the existing `StudioFormSession` section rhythm.
|
||||
|
||||
This slice lands the visible section and its staged-edit shell contract before full family-specific behavior is wired.
|
||||
|
||||
## Objective
|
||||
|
||||
After this PR:
|
||||
|
||||
- `Asset Details` contains a real `Bank Composition` section;
|
||||
- the section is a `VBox` section aligned with the existing details composition;
|
||||
- the section mirrors the `Runtime Contract` shell as closely as practical;
|
||||
- the section exposes `change`, `apply`, `reset`, and `cancel`;
|
||||
- outside editing it renders persisted state in read-only mode;
|
||||
- before behavior wiring is complete it can still render disabled/read-only internals instead of looking absent.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Bank Composition Section Shell Decision.md`](../decisions/Bank%20Composition%20Section%20Shell%20Decision.md)
|
||||
- [`./PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md)
|
||||
- [`./PR-10b-bank-composition-base-components.md`](./PR-10b-bank-composition-base-components.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add the `Bank Composition` section to `Asset Details`
|
||||
- align the shell with `Runtime Contract`
|
||||
- integrate `StudioFormSession` staged-edit lifecycle at the section boundary
|
||||
- render read-only or disabled internals when behavior is incomplete
|
||||
- show persisted state outside edit mode
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no family-specific bank rules yet
|
||||
- no final section-scoped coordinator yet
|
||||
- no workspace-bus events yet
|
||||
- no packer apply write path yet
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce the section host into `Asset Details`.
|
||||
2. Reuse the existing section/action-bar rhythm from `Runtime Contract`.
|
||||
3. Bind the section shell to a `StudioFormSession` lifecycle.
|
||||
4. Render read-only state outside edit mode.
|
||||
5. Render disabled/read-only internals where behavior is still pending.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the `Bank Composition` section is visible in `Asset Details`
|
||||
- the section shell matches the existing details-section rhythm
|
||||
- `change`, `apply`, `reset`, and `cancel` are part of the shell contract
|
||||
- outside edit mode the section shows persisted state in read-only form
|
||||
- the section does not appear blank or absent while later slices are still pending
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for section visibility and shell state
|
||||
- unit tests for `StudioFormSession`-driven shell transitions
|
||||
- UI smoke validation for read-only and editing shell modes
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
|
||||
- new bank-composition section controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
|
||||
- tests for details section-shell lifecycle
|
||||
@ -1,77 +0,0 @@
|
||||
# PR-10d Bank Composition Family Policies and Section Coordinator
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
Cross-domain impact: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Introduce the section-scoped coordinator for `Bank Composition`, built around `StudioFormSession<BankCompositionDraft>`, plus the first family-specific draft factories and policies.
|
||||
|
||||
This is the slice where the section starts behaving like an actual editor instead of just a shell.
|
||||
|
||||
## Objective
|
||||
|
||||
After this PR:
|
||||
|
||||
- `Bank Composition` has a section-scoped coordinator built around `StudioFormSession<BankCompositionDraft>`;
|
||||
- the section can enter edit mode and maintain draft state;
|
||||
- draft state can transfer rows between `available` and `selected`;
|
||||
- right-list ordering can update draft state;
|
||||
- family-specific rules are applied through draft factories and policies, not component-local logic.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Bank Composition Middleware and Staged Editing Decision.md`](../decisions/Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md)
|
||||
- [`./PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md)
|
||||
- [`./PR-10b-bank-composition-base-components.md`](./PR-10b-bank-composition-base-components.md)
|
||||
- [`./PR-10c-bank-composition-section-shell-and-form-session-integration.md`](./PR-10c-bank-composition-section-shell-and-form-session-integration.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add `BankCompositionDraft`
|
||||
- add the section-scoped coordinator around `StudioFormSession<BankCompositionDraft>`
|
||||
- add family-specific draft factories
|
||||
- add family-specific policies for:
|
||||
- transfer eligibility
|
||||
- reorder effects
|
||||
- capacity usage
|
||||
- hard-limit blockers
|
||||
- publish one section-facing view model for shell, lists, meter, blockers, and hints
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no public `workspaceBus` contract yet
|
||||
- no packer apply persistence yet
|
||||
- no final cross-domain mutation messages yet
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add the draft model for bank composition.
|
||||
2. Add the section-scoped coordinator around `StudioFormSession`.
|
||||
3. Add the first family-specific policy/factory implementations.
|
||||
4. Route dual-list and meter inputs through the coordinator view model.
|
||||
5. Support edit, reset, and cancel with real draft recomputation.
|
||||
6. Keep apply stubbed or disabled until the write path lands.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the section can enter editing mode and maintain draft state
|
||||
- dual-list moves update draft state through the coordinator
|
||||
- right-list ordering updates draft state through the coordinator
|
||||
- meter state reflects policy-driven capacity calculations
|
||||
- tile and sound family differences are modeled through policies, not through component branches
|
||||
- `reset` and `cancel` work through `StudioFormSession`
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for `BankCompositionDraft`
|
||||
- unit tests for tile and sound policy behavior
|
||||
- unit tests for transfer blocking and reorder effects
|
||||
- unit tests for `StudioFormSession` integration and draft lifecycle
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
|
||||
- family-specific policy and draft-factory classes under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...`
|
||||
- tests for coordinator and policy behavior
|
||||
- cross-domain touchpoint: any details data gaps exposed by the new policy logic
|
||||
@ -1,70 +0,0 @@
|
||||
# PR-10e Bank Composition WorkspaceBus Events and Local Orchestration
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
|
||||
## Briefing
|
||||
|
||||
Connect the `Bank Composition` section-scoped coordinator to the Studio workspace event model using the minimal notification-oriented contract already decided.
|
||||
|
||||
This slice keeps user actions local while making draft, capacity, and apply lifecycle visible to the rest of the workspace when needed.
|
||||
|
||||
## Objective
|
||||
|
||||
After this PR:
|
||||
|
||||
- the section keeps user commands local to the section-scoped coordinator;
|
||||
- the minimal `workspaceBus` notifications exist for bank-composition state changes;
|
||||
- external observers can react to draft, capacity, and apply lifecycle without owning section-local commands.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Bank Composition WorkspaceBus Interaction Decision.md`](../decisions/Bank%20Composition%20WorkspaceBus%20Interaction%20Decision.md)
|
||||
- [`./PR-10d-bank-composition-family-policies-and-section-coordinator.md`](./PR-10d-bank-composition-family-policies-and-section-coordinator.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add the first public bank-composition events:
|
||||
- `BankCompositionDraftChanged`
|
||||
- `BankCompositionCapacityChanged`
|
||||
- `BankCompositionApplyRequested`
|
||||
- `BankCompositionApplied`
|
||||
- `BankCompositionApplyFailed`
|
||||
- keep section-local actions local to the coordinator
|
||||
- publish capacity notifications with:
|
||||
- `progress`
|
||||
- `severity`
|
||||
- `blocked`
|
||||
- wire section subscribers/publishers as needed inside `Asset Details`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no conversion of all section actions into public bus commands
|
||||
- no cross-workspace event taxonomy expansion beyond the minimal first-wave set
|
||||
- no packer write-path implementation in this slice
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add the event classes and payloads.
|
||||
2. Publish draft and capacity notifications from the coordinator.
|
||||
3. Publish apply-requested/applied/apply-failed lifecycle notifications at the right boundaries.
|
||||
4. Keep move/reorder/edit/reset/cancel orchestration local.
|
||||
5. Add tests for event publication and subscription behavior.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the minimal first-wave bank-composition events exist on `workspaceBus`
|
||||
- user actions such as move and reorder are not exposed as public bus commands
|
||||
- capacity events publish absolute `0..1` progress plus severity and blocked state
|
||||
- apply lifecycle notifications are observable outside the section
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for event publication
|
||||
- unit tests for event payload correctness
|
||||
- unit tests confirming section-local actions remain local
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
|
||||
- tests for bank-composition event flow
|
||||
@ -1,76 +0,0 @@
|
||||
# PR-10f Bank Composition Apply Through Packer and Snapshot Refresh
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
Cross-domain impact: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
Close the write path for `Bank Composition` by routing `apply` through the packer service and rebinding the section from refreshed persisted state.
|
||||
|
||||
This is the slice where the section stops being draft-only and becomes a real persisted editor.
|
||||
|
||||
## Objective
|
||||
|
||||
After this PR:
|
||||
|
||||
- clicking `apply` sends the selected ordered files to packer;
|
||||
- packer owns validation, manifest persistence, and minimal runtime snapshot refresh;
|
||||
- `asset.json` persistence flows through `artifacts`, not `inputsByRole`;
|
||||
- successful apply rebinds the section from refreshed persisted state;
|
||||
- failed apply preserves the draft and keeps the section in editing mode.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Bank Composition Persistence and Snapshot Propagation Decision.md`](../decisions/Bank%20Composition%20Persistence%20and%20Snapshot%20Propagation%20Decision.md)
|
||||
- [`./PR-10d-bank-composition-family-policies-and-section-coordinator.md`](./PR-10d-bank-composition-family-policies-and-section-coordinator.md)
|
||||
- [`./PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md`](./PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md)
|
||||
- cross-domain dependency: packer-side message, persistence, and snapshot-refresh support for bank-composition apply
|
||||
|
||||
## Scope
|
||||
|
||||
- route section `apply` through the packer service boundary
|
||||
- send selected ordered files from Studio to packer
|
||||
- persist selection through `asset.json` `artifacts`
|
||||
- refresh minimal runtime/details state after successful apply
|
||||
- rebind the section from refreshed persisted state
|
||||
- preserve draft state on apply failure
|
||||
- surface local failure state plus `BankCompositionApplyFailed`
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no direct `asset.json` writes from Studio
|
||||
- no fallback write path through legacy `inputsByRole`
|
||||
- no broader manifest migration outside this flow
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the Studio-to-packer apply request path for bank composition.
|
||||
2. Integrate section `apply` with the packer service.
|
||||
3. Update the Studio side to await success/failure and rebind accordingly.
|
||||
4. Land the paired packer-side persistence and minimal snapshot refresh support.
|
||||
5. Add regression tests for success and failure behavior.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Studio does not write `asset.json` directly for bank composition
|
||||
- `apply` is executed by packer
|
||||
- selected ordered files are persisted through `artifacts`
|
||||
- after success, the section leaves edit mode and reloads from refreshed persisted state
|
||||
- after failure, the section stays in edit mode and the draft is preserved
|
||||
- apply lifecycle notifications reflect the actual result of the packer call
|
||||
|
||||
## Validation
|
||||
|
||||
- Studio unit tests for apply success rebinding
|
||||
- Studio unit tests for apply failure preserving draft state
|
||||
- packer tests for `artifacts` persistence and minimal snapshot refresh
|
||||
- UI smoke validation for apply, success, and failure flows
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/projects/...`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/...`
|
||||
- `prometeu-packer/src/main/java/p/packer/...`
|
||||
- `asset.json` persistence handling under the packer write path
|
||||
- Studio and packer tests for bank-composition apply
|
||||
@ -1,166 +0,0 @@
|
||||
# PR-11 Pack Wizard Shell and Packer Contract Consumption
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
Cross-domain impact: `docs/packer`
|
||||
|
||||
## Briefing
|
||||
|
||||
The `Pack` action in the `Assets` workspace is now closed as a Studio wizard over packer-owned operations.
|
||||
|
||||
The Studio decision already fixes the operational boundary:
|
||||
|
||||
- Studio is the shell;
|
||||
- packer owns summary, validation, pack execution, progress, and result semantics;
|
||||
- the wizard has four phases:
|
||||
`Summary`, `Validation`, `Packing`, `Result`;
|
||||
- validation runs only on the current `registered + included in build` set;
|
||||
- blocking diagnostics stop the flow before execution;
|
||||
- the first wave is non-cancelable.
|
||||
|
||||
The packer-side API PR also defines the contracts that Studio must consume:
|
||||
|
||||
- pack summary
|
||||
- pack validation
|
||||
- pack execution
|
||||
|
||||
This PR implements the Studio side of that contract.
|
||||
|
||||
References:
|
||||
|
||||
- [`../decisions/Pack Wizard in Assets Workspace Decision.md`](../decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
- [`../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the `Pack` wizard shell in the `Assets` workspace and bind it to the public packer contracts for summary, validation, progress, and result.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`../decisions/Pack Wizard in Assets Workspace Decision.md`](../decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
||||
- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
- cross-domain reference:
|
||||
[`../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- add a real `Pack` action entry point in the `Assets` workspace action bar
|
||||
- open a dedicated modal wizard from that button
|
||||
- implement the wizard shell with four explicit phases:
|
||||
- `Summary`
|
||||
- `Validation`
|
||||
- `Packing`
|
||||
- `Result`
|
||||
- consume packer summary API for the first phase
|
||||
- consume packer validation API for the second phase
|
||||
- consume packer pack execution API for the third phase
|
||||
- bind packer operation progress to the wizard progress UI
|
||||
- render result data from the final pack execution response
|
||||
- show blocking diagnostics by default in `Validation`
|
||||
- allow developer drill-down on per-asset validation entries
|
||||
- keep `Packing` non-editable and non-cancelable in the first wave
|
||||
- keep companion artifacts in secondary drill-down in `Result`
|
||||
- allow a `dumb` future-facing export/copy button without real behavior if the shell needs a visible reminder
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no local Studio recomputation of build-set semantics
|
||||
- no local Studio validation engine for pack gating
|
||||
- no fake timer-based progress
|
||||
- no cancellation in the first wave
|
||||
- no direct implementation of packer semantics inside Studio
|
||||
- no asset-details-local `Pack`; this remains a workspace-level flow
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Wire the `Pack` action in the workspace action bar to open the new wizard.
|
||||
|
||||
2. Build a dedicated wizard shell control for the `Assets` workspace.
|
||||
The shell should own:
|
||||
- phase navigation
|
||||
- modal presentation
|
||||
- loading states
|
||||
- error surfaces
|
||||
- binding to packer responses and progress events
|
||||
|
||||
3. Implement the `Summary` phase as packer-backed preflight.
|
||||
Rules:
|
||||
- request pack summary on open;
|
||||
- do not reconstruct counts from navigator rows;
|
||||
- show the canonical artifact name `assets.pa`;
|
||||
- show the build-set counts returned by packer.
|
||||
|
||||
4. Implement the `Validation` phase as packer-backed gate inspection.
|
||||
Rules:
|
||||
- call the validation API explicitly;
|
||||
- render aggregate counts and per-asset entries;
|
||||
- show blocking diagnostics by default;
|
||||
- allow drill-down to inspect more context on each asset;
|
||||
- block advance into `Packing` when validation fails.
|
||||
|
||||
5. Implement the `Packing` phase as an operational waiting surface.
|
||||
Rules:
|
||||
- call pack execution explicitly only after successful validation;
|
||||
- show progress bar and current-step text from packer-driven state;
|
||||
- keep the modal non-editable;
|
||||
- do not expose real cancel behavior in the first wave.
|
||||
|
||||
6. Implement the `Result` phase as packer-result rendering.
|
||||
Rules:
|
||||
- show final status;
|
||||
- show total assets packed;
|
||||
- show elapsed time when available from the contract;
|
||||
- keep `assets.pa` visible in the main summary;
|
||||
- move companion artifacts into secondary drill-down.
|
||||
|
||||
7. Integrate the operation with Studio progress and activity surfaces where appropriate.
|
||||
The wizard-local progress surface is primary during execution, but existing global operational surfaces should remain coherent with the same operation.
|
||||
|
||||
8. Keep the implementation boundary strict.
|
||||
Studio may orchestrate calls and render states, but it must not decide:
|
||||
- what the pack set is;
|
||||
- what counts as blocking;
|
||||
- how `asset_table` ordering is determined;
|
||||
- or what artifacts were emitted beyond what packer reports.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- clicking `Pack` in the `Assets` workspace opens a dedicated modal wizard
|
||||
- the wizard has explicit `Summary`, `Validation`, `Packing`, and `Result` phases
|
||||
- `Summary` is populated from packer summary data rather than local UI reconstruction
|
||||
- `Validation` is populated from packer validation data
|
||||
- validation failure blocks transition into `Packing`
|
||||
- blocking diagnostics are visible by default in the validation phase
|
||||
- per-asset drill-down exists for developer inspection
|
||||
- `Packing` shows packer-driven progress and remains non-editable
|
||||
- the first wave does not expose real cancellation
|
||||
- `Result` renders final packer result data and keeps companion artifacts secondary
|
||||
- the Studio implementation remains a shell over packer contracts rather than a second semantic engine
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for wizard phase state transitions
|
||||
- unit tests for mapping summary response into the `Summary` phase
|
||||
- unit tests for validation gating and blocked advance into `Packing`
|
||||
- unit tests for per-asset validation drill-down state
|
||||
- unit tests for progress binding from packer operation state into the wizard progress UI
|
||||
- unit tests for result rendering from pack execution response
|
||||
- smoke test for:
|
||||
- open wizard
|
||||
- load summary
|
||||
- run validation
|
||||
- stop on blockers
|
||||
- advance on valid state
|
||||
- show packing progress
|
||||
- render final result
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md` if the wizard shell behavior needs more explicit normative wording
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/**`
|
||||
- `prometeu-studio/src/main/java/p/studio/events/**` if new UI-local orchestration events are needed
|
||||
- `prometeu-studio/src/main/resources/i18n/messages.properties`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/**`
|
||||
@ -2,6 +2,12 @@
|
||||
|
||||
This directory contains executable plans for Studio work.
|
||||
|
||||
Current retained set:
|
||||
|
||||
- none
|
||||
|
||||
The previous Studio execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/).
|
||||
|
||||
## Purpose
|
||||
|
||||
A Studio pull-request or plan artifact packages a decision into an implementable sequence.
|
||||
@ -36,37 +42,5 @@ A Studio plan should usually include:
|
||||
|
||||
## Current Queue
|
||||
|
||||
The current Studio execution queue is:
|
||||
|
||||
1. [`PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
2. [`PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md)
|
||||
3. [`PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
4. [`PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
5. [`PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
6. [`PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md)
|
||||
7. [`PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md)
|
||||
8. [`PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
||||
9. [`PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
||||
10. [`PR-07e-assets-refactor-cleanup-and-regression-coverage.md`](./PR-07e-assets-refactor-cleanup-and-regression-coverage.md)
|
||||
11. [`PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md`](./PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md)
|
||||
12. [`PR-06-project-scoped-studio-state-and-activity-persistence.md`](./PR-06-project-scoped-studio-state-and-activity-persistence.md)
|
||||
|
||||
The `PR-07` family is a corrective refactor pass for the current `Assets` implementation.
|
||||
It exists to replace the refresh-heavy direction with lifecycle-managed, event-driven ownership.
|
||||
It also establishes the intended Studio-wide workspace framework, with `Assets` as the first consumer and proof point.
|
||||
|
||||
`PR-08` is the package-topology and subscription-ownership follow-up for that same direction.
|
||||
It enforces list/details package boundaries and requires every panel to consume the workspace bus directly.
|
||||
|
||||
Recommended execution order:
|
||||
|
||||
`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e -> PR-07a -> PR-07b -> PR-07c -> PR-07d -> PR-07e -> PR-08 -> PR-06`
|
||||
|
||||
Next planned family for `Bank Composition`:
|
||||
|
||||
13. [`PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md)
|
||||
14. [`PR-10b-bank-composition-base-components.md`](./PR-10b-bank-composition-base-components.md)
|
||||
15. [`PR-10c-bank-composition-section-shell-and-form-session-integration.md`](./PR-10c-bank-composition-section-shell-and-form-session-integration.md)
|
||||
16. [`PR-10d-bank-composition-family-policies-and-section-coordinator.md`](./PR-10d-bank-composition-family-policies-and-section-coordinator.md)
|
||||
17. [`PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md`](./PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md)
|
||||
18. [`PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md`](./PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md)
|
||||
When a new Studio execution wave starts, add only the plans that still represent pending work.
|
||||
Do not repopulate this directory with already-absorbed historical implementation slices.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user