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