prometeu-studio/docs/studio/decisions/Bank Composition Section Shell Decision.md

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 Composition Base Components Decision.md

This decision closes the shell direction discussed in:

• 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 Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md
• Studio specs: 4. Assets Workspace Specification.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.