asset walker (WIP)

This commit is contained in:
2026-03-24 13:42:49 +00:00
parent c4b7acab6f
commit 1c17562cc9
11 changed files with 482 additions and 17 deletions
@@ -35,7 +35,7 @@ The first-wave projection rules are:
The first DTO revision starts with these fields:
- `fileId/path`
- `path`
- `displayName`
- `size`
- `lastModified`
@@ -7,7 +7,7 @@ Cross-Domain Impact: `docs/packer`
## Context
`Bank Composition` needs a control layer above the new UI components because:
`Bank Composition` needs a section-scoped coordinator above the new UI components because:
- `StudioDualListView<T>` is intentionally dumb;
- `StudioAssetCapacityMeter` is intentionally dumb;
@@ -33,7 +33,7 @@ This decision closes the middleware direction discussed in:
## Decision
Adopt a dedicated bank-composition middleware/controller built around `StudioFormSession<BankCompositionDraft>`.
Adopt a dedicated bank-composition section-scoped coordinator built around `StudioFormSession<BankCompositionDraft>`.
The first-wave rules are:
@@ -43,7 +43,7 @@ The first-wave rules are:
4. family-specific variation must come from draft factories and bank-composition policies offered per asset family;
5. `apply` may remain stubbed or disabled until persistence is wired, but the session contract should already exist.
The middleware/controller owns orchestration around the form session, including:
The section-scoped coordinator owns orchestration around the form session, including:
- translating persisted section state into session source/draft state;
- beginning edit mode;
@@ -55,7 +55,7 @@ The middleware/controller owns orchestration around the form session, including:
- calculating capacity state;
- calculating hard-limit blockers and hints.
The middleware/controller should publish one section-facing view model that includes:
The section-scoped coordinator should publish one section-facing view model that includes:
- shell state such as editing mode, dirty state, and action availability;
- left and right list state;
@@ -67,7 +67,7 @@ The middleware/controller should publish one section-facing view model that incl
This is the simplest design that matches the actual codebase.
`StudioFormSession` already provides the staged-edit lifecycle the section needs.
Creating a second middleware-specific session model would duplicate behavior for no gain.
Creating a second coordinator-specific session model would duplicate behavior for no gain.
At the same time, subclassing `StudioFormSession` is the wrong variation point.
The current class is final, and more importantly the lifecycle does not change by asset family.
@@ -81,7 +81,7 @@ The following constraints now apply:
1. `StudioFormSession<BankCompositionDraft>` is the only staged-edit core for the section in the first wave;
2. asset-family differences must be modeled outside `StudioFormSession`;
3. the middleware/controller remains section-specific and should not become a platform-wide bank manager abstraction;
3. the section-scoped coordinator remains section-specific and should not become a platform-wide bank manager abstraction;
4. dumb UI components consume derived state and do not own bank rules;
5. the section-facing output must be consolidated into one view model rather than scattered state channels.
@@ -89,7 +89,7 @@ The following constraints now apply:
This decision does not yet define:
- the exact Java class names or package layout for the middleware/controller, policies, or draft factories;
- the exact Java class names or package layout for the section-scoped coordinator, policies, or draft factories;
- the exact shape of `BankCompositionDraft`;
- the `workspaceBus` event contract;
- persistence/apply integration with packer;
@@ -103,12 +103,12 @@ This decision does not yet define:
- Studio specs:
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Studio code:
`StudioFormSession` integration, `Bank Composition` section controller/middleware, family-specific draft factories, and family-specific bank-composition policies
`StudioFormSession` integration, `Bank Composition` section-scoped coordinator, family-specific draft factories, and family-specific bank-composition policies
## Validation Notes
Examples implied by this decision:
- a tile family and a sound family can share the same `StudioFormSession` lifecycle while using different capacity/blocker policies;
- the dual list and meter can stay dumb because the middleware/controller supplies already-derived state;
- the dual list and meter can stay dumb because the section-scoped coordinator supplies already-derived state;
- when persistence is not wired yet, `beginEdit`, `reset`, and `cancel` still work through the shared form-session model.
@@ -39,14 +39,14 @@ Route `Bank Composition` apply through packer and persist selection under `asset
The first-wave rules are:
1. Studio must not write `asset.json` directly;
2. packer owns persistence of selected bank-composition files;
2. the packer service owns validation, persistence, and minimal snapshot refresh for selected bank-composition files;
3. `artifacts` replaces the older `inputsByRole` representation for this flow;
4. selected file order must remain explicit in persisted data rather than relying on array position alone;
5. after a successful apply, Studio must refresh from persisted state rather than trusting stale draft state.
The minimal successful apply flow is:
1. Studio submits the selected ordered files to packer;
1. Studio submits the selected ordered files to the packer service;
2. packer updates `asset.json` under the `artifacts` representation;
3. packer refreshes the minimal runtime snapshot state required by `Asset Details`;
4. Studio rebinds the section from that refreshed persisted state;
@@ -74,6 +74,9 @@ This keeps write ownership in the correct domain boundary.
Packer already owns asset mutation and runtime refresh logic.
Letting Studio write manifests directly would duplicate rules and create drift between UI and runtime behavior.
The Studio should only submit the apply request and react to the result.
The packer service is the owner of validation, persistence, and state propagation.
Refreshing from persisted state after success is also necessary.
Otherwise the section would keep trusting stale draft state and could diverge from what packer actually accepted and wrote.
@@ -30,7 +30,7 @@ Adopt a minimal, notification-oriented first-wave `workspaceBus` contract for `B
The first-wave rules are:
1. user actions should stay local to the bank-composition middleware/controller whenever possible;
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.
@@ -43,7 +43,7 @@ The first-wave public notification set is:
- `BankCompositionApplied`
- `BankCompositionApplyFailed`
The first-wave local-only action set remains inside the middleware/controller:
The first-wave local-only action set remains inside the section-scoped coordinator:
- `beginEdit`
- `moveToSelected`
@@ -54,6 +54,9 @@ The first-wave local-only action set remains inside the middleware/controller:
- `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`
@@ -65,7 +68,7 @@ The first-wave capacity notification should expose at least:
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 middleware/controller is already the right local place for section commands and recalculation.
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.
@@ -95,7 +98,7 @@ This decision does not yet define:
- Studio specs:
[`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Studio code:
bank-composition middleware/controller, event definitions, and event subscribers in `Asset Details`
bank-composition section-scoped coordinator, event definitions, and event subscribers in `Asset Details`
## Validation Notes
@@ -103,4 +106,5 @@ 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.
- 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.