# 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.