prometeu-studio/docs/studio/agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md

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.