# UpdatePurchasePriceList

## Permission Scope

purchasePricing

## Overview

UpdatePurchasePriceList updates descriptive metadata, validity notes, or deterministic priority on an existing supplier price list without changing historical order snapshots.

## Business Rules

- Target price list must exist
- Company and supplier ownership are immutable
- Updating a price list never rewrites purchase orders that already snapshotted one of its rules
- Priority changes must preserve deterministic ordering for rule selection

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Price list exists?}
    B -->|No| C[Return PRICE_LIST_NOT_FOUND]
    B -->|Yes| D{Ownership unchanged and priority valid?}
    D -->|No| E[Return validation error]
    D -->|Yes| F[Update price list]
    F --> G[Return updated list]
```

## External Dependencies

- None

## Error Scenarios

- **PRICE_LIST_NOT_FOUND**: Referenced purchase price list does not exist
- **IMMUTABLE_OWNER_CHANGE**: Update attempted to change the supplier or company owner
- **INVALID_LIST_PRIORITY**: List priority conflicts with deterministic supplier or rule ordering

## Test Cases

- updates metadata on an active price list
- updates metadata on an inactive price list
- preserves historical purchase-order snapshots after update
- returns error when price list does not exist
- returns error when supplier or company ownership is changed
- returns error when updated priority is invalid
- returns error when company ownership is changed
