prometeu-studio/docs/studio/pull-requests/PR-07d-asset-mutation-and-structural-sync-orchestration.md

PR-07d Asset Mutation and Structural Sync Orchestration

Domain owner: docs/studio

Briefing

Replace the current mutation flow that falls back to refresh() after many operations with an event-directed orchestration model.

The key rule is:

• local patches stay local;
• only structural workspace changes trigger structural sync;
• structural sync is explicit and typed, not an incidental rerender path.

Objective

Make asset operations compatible with the event-driven component model.

After this PR:

• direct mutations publish patch or structural-sync events according to their actual impact;
• row and details controls react to targeted operation results when possible;
• create/remove/relocate or other structural operations request a workspace sync explicitly;
• the workspace no longer treats every successful operation as a reason to reload everything.
• the local-patch versus structural-sync rule is available as a reusable Studio workspace orchestration rule.

Dependencies

• ./PR-07a-assets-event-topology-and-lifecycle-foundation.md
• ./PR-07b-asset-navigator-and-row-subscriptions.md
• ./PR-07c-asset-details-and-form-lifecycle.md
• ./PR-05d-assets-activity-progress-and-logs-integration.md
• ./PR-05e-assets-staged-mutations-preview-and-apply.md

Scope

• classify operations by update impact:
  • local summary patch
  • details patch
  • structural workspace sync
  • failure retention/reporting
• extract reusable orchestration helpers or contracts where the distinction is cross-workspace rather than asset-specific
• route mutation preview/apply results through typed events
• replace generic refresh() fallbacks for non-structural success paths
• keep progress/log/activity integration aligned with the new orchestration path
• make structural sync requests explicit and testable

Non-Goals

• no redesign of packer service semantics
• no generic Studio-wide command bus abstraction in this slice
• no persistence work unrelated to asset-workspace orchestration

Execution Method

1. Define operation-result events and structural-sync request events.
2. Map each mutation action to its update strategy.
3. Update mutation flows to publish events instead of directly forcing global workspace refresh.
4. Keep structural reload only for actions that truly change collection shape or asset identity.
5. Wire progress, logs, and activity to the new operation flow without reintroducing redraw coupling.

Acceptance Criteria

• include/exclude, preload, and similar local operations can update via targeted events
• create/register/remove/relocate use explicit structural-sync flow only when required
• mutation preview and apply flows do not directly rebuild navigator and details by default
• activity/log/progress signals remain correct under the new orchestration
• the remaining structural sync path is narrow, explicit, and justified by actual data-shape changes
• the orchestration rule is documented as reusable Studio behavior, not an Assets exception

Validation

• unit tests for operation-to-update-strategy mapping
• unit tests for structural-sync event publication
• unit tests for targeted patch propagation after successful operations
• UI smoke validation for register/include/exclude/relocate/remove flows

Affected Artifacts

• prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java
• mutation and orchestration classes under prometeu-studio/src/main/java/p/studio/workspaces/assets/...
• prometeu-studio/src/main/java/p/studio/events/...
• tests for mutation orchestration and structural sync behavior