# Asset Bank Composition Persistence and Snapshot Propagation Agenda

Status: Open
Domain Owner: `docs/studio`
Cross-Domain Impact: `docs/packer`

## Problem

When the developer clicks `apply`, the selected files for bank composition must be persisted and reflected back into runtime state.

That write path spans Studio and packer concerns:

- staged selected files must be serialized into `asset.json`;
- the older `inputsByRole` shape should give way to the newer `artifacts` shape;
- the minimal runtime snapshot must reflect the persisted result after apply.

## Context

The earlier agendas in this sequence assume `apply` may remain disabled or stubbed until persistence is ready.
This agenda isolates the write-path discussion so the rest of the UI can progress first.

The current direction is already mostly known:

- persistence should happen through packer, not by having Studio write manifest files directly;
- selected composition should be stored in `asset.json`;
- runtime state should be refreshed after persistence so `Asset Details` stays coherent.

## Options

1. Let Studio write `asset.json` directly.
2. Route `apply` through packer services and let packer own manifest persistence plus snapshot refresh.
3. Persist only to runtime state first and defer manifest persistence.

## Tradeoffs

1. Direct manifest writes from Studio would bypass packer ownership and create duplicate write rules.
2. A packer-owned write path is cleaner and aligns with existing asset mutation flows.
3. Runtime-only persistence would create an unstable editing model and almost certainly drift from disk state.

## Recommendation

Route `apply` through packer and persist selected files into `asset.json` using the newer `artifacts` representation.

Baseline expectations:

- `apply` submits the selected ordered files to packer;
- packer updates `asset.json`;
- packer propagates the resulting minimal state back into the runtime snapshot;
- Studio refreshes the section from the updated details/snapshot state instead of trusting stale draft data.

### Persistence Baseline

The first-wave persistence direction is:

- `artifacts` replaces the older `inputsByRole` representation in `asset.json`;
- the bank-composition selection should therefore persist through `artifacts`, not through a parallel legacy shape;
- selected file order should remain explicit in persisted data rather than relying on array position alone.

### Apply Refresh and Failure Baseline

After `apply`, the Studio should not trust stale draft state.

The first-wave refresh baseline is:

- packer persists the selected ordered files into `asset.json`;
- packer refreshes the minimal runtime snapshot state needed by `Asset Details`;
- the Studio rebinds the section from the refreshed persisted state and returns the section to consistent read-only mode.

The minimum refreshed state should include:

- persisted `selected` rows;
- the current `available` projection for details;
- recalculated capacity state;
- recalculated blockers or eligibility state relevant to the section.

If `apply` fails:

- the draft must not be discarded;
- the section must remain in editing mode;
- the middleware/controller should publish `BankCompositionApplyFailed`;
- the UI should show a local error or hint surface;
- the user should still be able to retry, reset, or cancel.

## Open Questions

No open questions remain in this agenda wave.

### Resolved In This Agenda Wave

The following points are now closed:

1. `artifacts` should replace the older `inputsByRole` shape rather than coexist with it for bank-composition persistence.
2. After `apply`, packer should refresh the minimal snapshot state required by `Asset Details` and Studio should rebind from that refreshed persisted state.
3. If `apply` fails, the draft remains intact, the section stays in editing mode, and the UI surfaces a local failure state while preserving retry, reset, and cancel.

## Next Suggested Step

Turn this into a cross-domain `decision` or a paired `docs/studio` + `docs/packer` decision set that closes the apply write path.