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