discussion framework migration
This commit is contained in:
@@ -0,0 +1,364 @@
|
||||
# Assets Workspace Specification
|
||||
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-studio`
|
||||
- the Studio `Assets` workspace
|
||||
- packer-facing Studio service integration for asset browsing, inspection, diagnostics, and staged mutations
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the normative Studio contract for the `Assets` workspace.
|
||||
|
||||
This specification stabilizes:
|
||||
|
||||
- the information architecture of the workspace,
|
||||
- the navigation and selection model,
|
||||
- the selected-asset details structure,
|
||||
- the relationship between activity, progress, and logs,
|
||||
- and the preview/confirm/apply flow for sensitive mutations.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification extends:
|
||||
|
||||
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
|
||||
|
||||
For packer-facing semantics, this specification must align with:
|
||||
|
||||
- [`../../packer/specs/1. Domain and Artifact Boundary Specification.md`](../../packer/specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`](../../packer/specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../../packer/specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local behavior.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
The `Assets` workspace is a Studio view over packer services.
|
||||
|
||||
The workspace must assume:
|
||||
|
||||
- registered and unregistered assets may coexist inside `assets/`;
|
||||
- unregistered assets remain visible but excluded from builds;
|
||||
- assets may aggregate many internal inputs;
|
||||
- runtime-facing output contract data exists for each asset;
|
||||
- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services;
|
||||
- packer-facing operational freshness may surface states such as `healthy`, `stale`, `diverged`, `reconciling`, or `failed`.
|
||||
|
||||
Packer-backed operational events consumed by this workspace are expected to enter Studio through the container-owned typed event bus path rather than through workspace-local ad hoc bus creation.
|
||||
|
||||
## Workspace Model
|
||||
|
||||
The `Assets` workspace is:
|
||||
|
||||
- `asset-first`,
|
||||
- `path-aware`,
|
||||
- didactic toward the packer model,
|
||||
- and explicitly not a raw filesystem explorer clone.
|
||||
|
||||
The workspace must help the user understand:
|
||||
|
||||
- what the asset registration and build status are;
|
||||
- where the asset root lives;
|
||||
- which internal inputs belong to that asset;
|
||||
- what the asset declares toward the runtime-facing contract;
|
||||
- which operations are safe, staged, blocked, or destructive;
|
||||
- whether the current view reflects healthy, stale, diverged, or reconciling packer state.
|
||||
|
||||
The `Assets` workspace is also the first concrete consumer of the Studio event-driven workspace framework.
|
||||
|
||||
That means:
|
||||
|
||||
- `Assets` must prove the canonical Studio workspace architecture in real use;
|
||||
- reusable lifecycle and projection patterns extracted here should be consumable by future Studio workspaces;
|
||||
- `Assets` must not rely on a monolithic workspace root that redraws most of the UI after local interactions.
|
||||
|
||||
## Baseline Layout
|
||||
|
||||
The baseline workspace layout is:
|
||||
|
||||
- a custom `Asset Tree` / `Asset Navigator` on the left;
|
||||
- a selected-asset details area in the main panel;
|
||||
- inline diagnostics and action surfaces attached to the selected asset;
|
||||
- global `Activity` in the shell right-side utility area;
|
||||
- logs in the lower workspace region.
|
||||
|
||||
Filesystem structure may be visible and actionable as supporting context, but it is not the primary identity model of the workspace.
|
||||
|
||||
## Component Ownership Rules
|
||||
|
||||
The `Assets` workspace must be implemented as a composition root plus lifecycle-managed child controls.
|
||||
|
||||
Rules:
|
||||
|
||||
- the workspace root should coordinate service calls, workspace state, and structural synchronization;
|
||||
- the workspace root should not own the render and update path of every navigator row, details section, and form control directly;
|
||||
- the navigator host, asset rows, selected-asset details host, and details-internal sections/forms should subscribe only to the events and state they consume;
|
||||
- event-consuming controls must subscribe only while mounted in the UI tree;
|
||||
- reusable framework primitives should be consumed where the Studio already provides them instead of duplicating local refresh-oriented mechanisms.
|
||||
|
||||
## Asset Navigator Rules
|
||||
|
||||
### Primary Navigation Unit
|
||||
|
||||
- The primary navigation unit is the asset, not the raw file.
|
||||
- The navigator must not degrade into a generic file tree.
|
||||
- Grouping may reflect path or parent-folder structure, but asset nodes remain the primary navigable and selectable unit.
|
||||
|
||||
### Visual Rules
|
||||
|
||||
- The left navigation surface must be a custom `Asset Tree` / `Asset Navigator`.
|
||||
- Asset nodes must expose strong visual semantics through icons, badges, and state styling.
|
||||
- Asset nodes must surface:
|
||||
- registration status,
|
||||
- build participation,
|
||||
- diagnostics presence,
|
||||
- preload intent,
|
||||
- and broad asset family or type where available.
|
||||
- Path context may appear as secondary information.
|
||||
|
||||
### Filters and Search
|
||||
|
||||
- The baseline filters are:
|
||||
- `Registered`
|
||||
- `Unregistered`
|
||||
- `Diagnostics`
|
||||
- `Preload`
|
||||
- The navigator must support textual search.
|
||||
- Baseline search must cover at least:
|
||||
- `asset_name`
|
||||
- asset root path
|
||||
- path context
|
||||
|
||||
### Workspace Actions
|
||||
|
||||
- Workspace-scoped actions must appear above the main asset workspace split, not inside the navigator list region.
|
||||
- Workspace-scoped actions must not be mixed into the selected-asset details surface.
|
||||
- Workspace actions should remain visible without requiring a selected asset.
|
||||
- Global asset-manager actions such as `Add Asset`, `Doctor`, and `Pack` belong to this workspace-level action area.
|
||||
|
||||
### Navigator Actions
|
||||
|
||||
- Navigator-local controls may include search and filters that are specifically about asset discovery and navigation.
|
||||
|
||||
### Selection Rules
|
||||
|
||||
- The baseline navigator is single-select.
|
||||
- Registered asset selection must be preserved by `asset_id`.
|
||||
- Unregistered selection must be preserved by asset root path until the asset becomes registered.
|
||||
- If an asset changes state while preserving identity, selection must remain attached to it.
|
||||
- If the selected asset is removed from the navigator, selection must clear explicitly.
|
||||
- Selection must never silently drift to another asset due to refresh ordering.
|
||||
|
||||
### Local Rendering Rules
|
||||
|
||||
- The workspace must use event-directed local redraws for routine interactions.
|
||||
- The navigator host must react to projection-level events rather than whole-workspace rerender requests.
|
||||
- Asset row items should react to row-scoped patch and selection events when identity is preserved.
|
||||
- Selecting an asset must update navigator selection styling and the selected-asset details surface without rebuilding the entire workspace shell.
|
||||
- Search and filter changes must redraw the navigator projection only.
|
||||
- Details-local interactions such as preview input selection, preview zoom, or runtime-contract edits must redraw the selected-asset details surface only.
|
||||
- Structural operations such as asset creation, removal, relocation, or full workspace reload may rebuild both navigator and details projections.
|
||||
- Workspace-scoped progress and logging updates must not force navigator or selected-asset details redraw unless the underlying projection actually changed.
|
||||
|
||||
### State Rules
|
||||
|
||||
- The navigator must define explicit `loading assets` state.
|
||||
- The navigator must define explicit `no assets` state.
|
||||
- The navigator must define explicit `no results` state.
|
||||
- The navigator must define explicit `workspace error` state.
|
||||
- The workspace must define explicit operational freshness states when packer runtime divergence is surfaced.
|
||||
- Unregistered assets must appear in the same navigator flow as registered assets.
|
||||
- Unregistered styling must communicate `present but not yet registered`, not `broken`.
|
||||
|
||||
### Inputs Expansion
|
||||
|
||||
- Internal inputs may appear only as optional expansion or inspection surfaces.
|
||||
- Inputs must not replace asset nodes as the default navigation unit.
|
||||
|
||||
## Selected Asset Details Rules
|
||||
|
||||
The selected asset view must use this stable composition:
|
||||
|
||||
1. top row with `Summary` and `Actions` side by side
|
||||
2. `Runtime Contract`
|
||||
3. `Inputs / Preview`
|
||||
4. `Diagnostics`
|
||||
|
||||
This composition is stable across asset families.
|
||||
|
||||
The selected-asset details area must follow component-local ownership.
|
||||
|
||||
Rules:
|
||||
|
||||
- the details host should react to details lifecycle events such as loading, ready, and error;
|
||||
- details sections should update independently when only one section's projection changed;
|
||||
- forms and preview-local controls should publish and consume narrow typed events rather than trigger full details rebuild by default.
|
||||
|
||||
### Summary
|
||||
|
||||
- `Summary` must always be present for a selected asset.
|
||||
- `Summary` must show:
|
||||
- `asset_name`
|
||||
- registration status
|
||||
- build participation
|
||||
- `asset_id` when available
|
||||
- family/type
|
||||
- asset root path
|
||||
|
||||
### Runtime Contract
|
||||
|
||||
- `Runtime Contract` must present runtime-facing asset output data in short, didactic form.
|
||||
- `Runtime Contract` must surface:
|
||||
- `output.format`
|
||||
- `codec`
|
||||
- `preload`
|
||||
- Runtime-facing output information must not require raw JSON inspection.
|
||||
|
||||
### Inputs / Preview
|
||||
|
||||
- `Inputs / Preview` must expose internal inputs as part of the selected asset.
|
||||
- Inputs should be structured by role where that information is available.
|
||||
- Preview should be available for previewable materials such as:
|
||||
- images
|
||||
- palettes
|
||||
- audio
|
||||
- text
|
||||
- similar lightweight input artifacts
|
||||
- Preview of derived output may exist, but input preview has baseline priority.
|
||||
|
||||
### Diagnostics
|
||||
|
||||
- Diagnostics for the selected asset must appear inline in the selected asset view.
|
||||
- Blockers, warnings, and hints must be distinguishable.
|
||||
- Inline diagnostics must not be replaced by raw logs.
|
||||
|
||||
### Actions
|
||||
|
||||
- Actions must be explicit.
|
||||
- Actions that target the selected asset must appear beside `Summary`, not in the navigator area.
|
||||
- Safe and routine actions must be visually separated from sensitive mutations.
|
||||
- Hidden or automatic repair behavior is not allowed in the selected-asset view.
|
||||
- If packer surfaces stale/diverged/reconciling state, the selected-asset view may expose explicit refresh or reconcile-oriented actions, but it must not invent repair semantics locally.
|
||||
|
||||
## Action Rules
|
||||
|
||||
- Registered assets excluded from builds must expose an explicit `Include In Build` action.
|
||||
- Primary actions for unregistered assets include `Register`.
|
||||
- `Register` is a direct action in Studio UX. If registration is valid, clicking it must register immediately without an extra acknowledgement step.
|
||||
- If registration is blocked, Studio may surface the blocking preview inline so the user can inspect why registration cannot proceed.
|
||||
- Sensitive actions such as `Exclude From Build`, `Remove`, and `Relocate` must be visually separated from routine actions.
|
||||
- Sensitive actions must not look interchangeable with routine actions.
|
||||
- `Relocate` must collect an explicit user-chosen destination root before the staged preview is generated.
|
||||
- Automatic relocation targets are not sufficient Studio UX for `Relocate`.
|
||||
- `Exclude From Build` and `Remove` must confirm in a modal review surface rather than an inline staged panel.
|
||||
|
||||
## Activity, Progress, and Logs Rules
|
||||
|
||||
### Activity
|
||||
|
||||
- `Activity` belongs to the global right-side shell panel.
|
||||
- `Activity` is the structured operational timeline of the Studio.
|
||||
- Activity entries must be user-oriented rather than service-trace-oriented.
|
||||
- Repetitive background events must be aggregated or summarized.
|
||||
- Significant lifecycle milestones should remain visible in the feed.
|
||||
|
||||
### Progress
|
||||
|
||||
- Progress must be visible globally in the shell.
|
||||
- Progress may also appear inline when the current asset or action clearly owns that progress.
|
||||
- Progress tick events must update progress state rather than create feed spam.
|
||||
|
||||
### Logs
|
||||
|
||||
- Logs belong to the lower workspace region as detailed textual output.
|
||||
- Logs are secondary drill-down, not the primary explanation surface.
|
||||
- The user must not need raw logs to understand ordinary operational state.
|
||||
|
||||
### Failure Retention
|
||||
|
||||
- Recent actionable failures must remain visible until acknowledged.
|
||||
- Failures tied to the selected asset should also surface inline in the selected asset view.
|
||||
- Critical failures must not disappear merely because low-value events continue to arrive.
|
||||
|
||||
## Staged Mutation Rules
|
||||
|
||||
Sensitive asset mutations are `preview-first`.
|
||||
|
||||
The review surface depends on the mutation class.
|
||||
|
||||
Inline staged panels are allowed for non-destructive blocked or inspect-only flows.
|
||||
|
||||
Modal review and confirmation is required for `Exclude From Build`, `Remove`, and relocation commits.
|
||||
|
||||
Routine state patches such as `preload`, `Include In Build`, and `Exclude From Build` must patch the affected asset projection locally when identity is preserved. Full workspace refresh is reserved for operations that change workspace structure or identity resolution.
|
||||
|
||||
Operation orchestration must follow this rule:
|
||||
|
||||
- local patch when stable identity and local projection are preserved;
|
||||
- explicit structural sync when collection shape, identity, or projection membership changes;
|
||||
- no routine mutation path should fall back to whole-workspace refresh merely for implementation convenience.
|
||||
|
||||
### Mutations Requiring Preview
|
||||
|
||||
- `Exclude From Build`
|
||||
- `Remove`
|
||||
- relocational changes such as move or rename of asset roots
|
||||
- batch operations
|
||||
|
||||
Navigator-level `Doctor` and `Pack`, plus asset-level `Include In Build` and successful `Register`, remain outside this sensitive mutation staging flow.
|
||||
|
||||
### Preview Content
|
||||
|
||||
- Preview must show affected assets.
|
||||
- Relocation preview must show the planned target root chosen by the user.
|
||||
- Preview must show proposed actions.
|
||||
- Preview must distinguish registry impact from workspace impact.
|
||||
- Preview must show blockers, warnings, and safe fixes as separate visual sections.
|
||||
- Preview must show diff-style effects such as:
|
||||
- create
|
||||
- move
|
||||
- delete
|
||||
- registry update
|
||||
|
||||
### Apply Rules
|
||||
|
||||
- `Apply` must remain disabled while blockers exist.
|
||||
- Batch operations must present an aggregate summary first.
|
||||
- Batch operations may expose drill-down detail after the aggregate summary.
|
||||
- Destructive or relocational actions must not bypass preview.
|
||||
|
||||
### Activity Integration
|
||||
|
||||
- `preview_ready` should surface in global `Activity`.
|
||||
- `action_applied` should surface in global `Activity`.
|
||||
- `action_failed` should surface in global `Activity`.
|
||||
- reconcile or divergence state transitions should remain visible when they affect current workspace truth.
|
||||
- The preview itself remains a workspace-local review surface.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
This specification does not define:
|
||||
|
||||
- the exact JavaFX component tree or control class structure of the `Assets` workspace;
|
||||
- final reusable component boundaries for all preview surfaces;
|
||||
- future multi-select or bulk-edit UX beyond the currently defined staged batch summary rules.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is satisfied when the Studio `Assets` workspace:
|
||||
|
||||
- navigates by assets rather than raw files;
|
||||
- preserves path awareness without collapsing into a file explorer;
|
||||
- explains the selected asset through summary, contract, inputs, diagnostics, and actions;
|
||||
- keeps activity, progress, and logs clearly separated;
|
||||
- stages sensitive mutations through preview-first flows;
|
||||
- proves the Studio event-driven workspace framework through lifecycle-managed local ownership;
|
||||
- and behaves as a didactic helper for the packer model.
|
||||
Reference in New Issue
Block a user