# RecordManufacturingCostSettlementAcknowledgment

## Permission Scope

productionOrder

## Overview

RecordManufacturingCostSettlementAcknowledgment persists the downstream accounting acknowledgment that a reviewed manufacturing cost handoff has been consumed by settlement processing. It is the only path that moves a reviewed summary to `SETTLED`.

## Business Rules

- Target cost summary must exist and be in `VARIANCE_REVIEWED`.
- Acknowledgment payload must match the reviewed summary's production order, summary reference, and settlement currency.
- Downstream accounting owns the acknowledgment payload; manufacturing may record it but must not fabricate it.
- An acknowledgment that is rejected, reversed, or superseded by downstream accounting must not settle the summary and requires a valid replacement acknowledgment before settlement can proceed.
- Successful recording sets the summary status to `SETTLED`.

## Process Flow

```mermaid
flowchart TD
    A[Receive settlement acknowledgment] --> B{Summary exists and is reviewed?}
    B -->|No| C[Return COST_SUMMARY_NOT_SETTLABLE]
    B -->|Yes| D[Validate payload identity and currency]
    D --> E{Payload valid?}
    E -->|No| F[Return ACKNOWLEDGMENT_MISMATCH]
    E -->|Yes| G{Downstream accepted and not superseded?}
    G -->|No| H[Return ACKNOWLEDGMENT_REJECTED_OR_SUPERSEDED]
    G -->|Yes| I[Persist acknowledgment and set SETTLED]
    I --> J[Return settled summary]
```

## External Dependencies

- None

## Error Scenarios

- **COST_SUMMARY_NOT_FOUND**: Referenced cost summary does not exist
- **COST_SUMMARY_NOT_SETTLABLE**: Summary is not in `VARIANCE_REVIEWED`.
- **ACKNOWLEDGMENT_MISMATCH**: Order, summary reference, or currency does not match the reviewed handoff.
- **ACKNOWLEDGMENT_REJECTED_OR_SUPERSEDED**: Downstream accounting rejected, reversed, or superseded the reviewed handoff, so the summary must remain in `VARIANCE_REVIEWED`.
- **ACKNOWLEDGMENT_SOURCE_INVALID**: Payload was not produced by the downstream settlement process.

## Test Cases

- records a valid downstream settlement acknowledgment and settles the summary
- returns error when the summary does not exist
- returns error when the summary is not variance reviewed
- returns error when the payload does not match the reviewed handoff
- returns error when downstream accounting rejects, reverses, or supersedes the reviewed handoff
- returns error when the acknowledgment source is invalid