# 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`](./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md)
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- cross-domain reference: [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md`](../../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