prometeu-studio/docs/studio/decisions/Bank Composition Details DTO Projection Decision.md

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

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 Agenda-03-Asset-Bank-Composition-Section-Shell.md 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: 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.