asset walker (WIP)
This commit is contained in:
@@ -0,0 +1,110 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,109 @@
|
||||
# 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:
|
||||
|
||||
- `fileId/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.
|
||||
@@ -0,0 +1,114 @@
|
||||
# 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 control layer 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 middleware/controller 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 middleware/controller 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 middleware/controller 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 middleware-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 middleware/controller 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 middleware/controller, 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 controller/middleware, 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 middleware/controller supplies already-derived state;
|
||||
- when persistence is not wired yet, `beginEdit`, `reset`, and `cancel` still work through the shared form-session model.
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
# 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. packer owns persistence of 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 packer;
|
||||
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.
|
||||
|
||||
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`.
|
||||
@@ -0,0 +1,85 @@
|
||||
# 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`.
|
||||
@@ -0,0 +1,106 @@
|
||||
# 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 middleware/controller 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 middleware/controller:
|
||||
|
||||
- `beginEdit`
|
||||
- `moveToSelected`
|
||||
- `moveToAvailable`
|
||||
- `moveUp`
|
||||
- `moveDown`
|
||||
- `reset`
|
||||
- `cancel`
|
||||
- `apply`
|
||||
|
||||
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 middleware/controller 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 middleware/controller, 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.
|
||||
@@ -2,7 +2,14 @@
|
||||
|
||||
This directory contains Studio decision records.
|
||||
|
||||
There are currently no retained Studio decision records.
|
||||
Current decision records:
|
||||
|
||||
- [`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)
|
||||
|
||||
The first Studio decision wave and the first asset workspace wave were already consolidated into:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user