prometeu-studio/docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md

PR-05 Sensitive Mutations, Preview/Apply, and Studio Write Adapter

Domain Owner: docs/packer

Briefing

Implement the packer-owned preview/apply mutation services and route Studio staged mutations through a write adapter instead of local filesystem rules.

This PR is where the current Studio staged mutation UI starts executing real packer semantics.

Objective

Deliver structured preview/apply services for register_asset, adopt_asset, forget_asset, remove_asset, quarantine, and relocation, plus the Studio adapter that maps packer mutation responses into the existing staged mutation UI.

Dependencies

• ./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md
• ../specs/2. Workspace, Registry, and Asset Identity Specification.md
• ../specs/5. Diagnostics, Operations, and Studio Integration Specification.md
• cross-domain reference: ../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md

Scope

• implement preview/apply service contracts for:
  • register_asset
  • adopt_asset
  • forget_asset
  • remove_asset
  • quarantine_asset
  • relocate_asset
• preserve explicit distinction between:
  • registry mutations
  • workspace mutations
  • blockers
  • warnings
  • safe fixes
• implement mutation serialization rules so conflicting write flows do not race
• implement the baseline single-writer semantic lane per project for sensitive mutation apply
• create the Studio write adapter for staged mutation preview/apply
• replace filesystem-only Studio mutation execution with packer-backed services

Non-Goals

• no doctor implementation yet
• no build artifact emission yet
• no generic cross-workspace mutation framework

Execution Method

1. Implement staged intent models and preview/apply response types in the packer.
2. Implement mutation handlers on top of registry and workspace services.
3. Serialize final mutation apply within a project-scoped write lane while keeping preview generation outside the commit-critical section when safe.
4. Add a Studio adapter that converts packer mutation responses into the current staged preview model and forwards packer-native lifecycle events into the Studio event bus.
5. Retire duplicated mutation semantics from Studio once the adapter path is stable.

Acceptance Criteria

• sensitive mutations run through packer preview/apply services
• Studio staged mutation UI no longer owns core mutation semantics
• relocation preserves asset_id and asset_uuid
• quarantine is explicit, previewable, and reversible in service semantics
• mutation failures remain actionable and structured
• conflicting mutation applies on the same project cannot commit concurrently
• mutation lifecycle can be surfaced to Studio without Studio inventing semantic outcomes

Validation

• packer tests for each sensitive mutation preview/apply path
• packer concurrency tests for same-project conflicting writes
• adapter tests for mapping packer responses into Studio preview models
• adapter tests for forwarding packer mutation lifecycle events into Studio events
• Studio smoke validation for preview/apply against the packer-backed path

Affected Artifacts

• prometeu-packer/**
• prometeu-studio/** mutation adapter and wiring
• mutation fixture workspaces