This commit is contained in:
2026-03-24 13:42:57 +00:00
parent d16a987949
commit 0e5e1669c2
98 changed files with 824 additions and 8449 deletions
+7 -2
View File
@@ -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.
+1 -8
View File
@@ -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.
+4 -9
View File
@@ -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/)
+5 -1
View File
@@ -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)
@@ -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)
@@ -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
View 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)
@@ -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/**`
+8 -34
View File
@@ -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.