# Spec Delta

## Purpose

Keep inventory quantities and attributed movement history consistent across checkout, warehouse operations, and future Work Orders.

## ADDED Requirements

### Requirement: Atomic posting
Posting SHALL commit movement, balance, required quarantine effects, and audit together. Physical SHALL remain greater than or equal to quarantined, which SHALL remain non-negative. PENDING and REJECTED movements SHALL have no posted stock effects.

#### Scenario: Required audit fails
- **WHEN** an audit write fails after balance processing
- **THEN** no movement, balance, approval, or related case change commits

#### Scenario: Competing requests
- **WHEN** two postings compete for stock sufficient for only one
- **THEN** at most one succeeds and the other receives 409 without negative availability

### Requirement: Retry-safe mutations
Clients SHALL retain an idempotency key for each logical mutation. Same actor, operation, key, and normalized payload SHALL return the original business result without duplicate effects. Conflicting key reuse SHALL return 409 without disclosing another actor's result.

#### Scenario: Response lost after commit
- **WHEN** the original requester retries with the same key and payload
- **THEN** the existing resource is returned without another ledger or audit entry

### Requirement: Controlled stock operations
ADMIN/SUPERVISOR SHALL post receipts, adjustments, returns, and reversals. Receipts/returns increase physical stock, issues decrease it, and adjustments require a reason. Quantity SHALL be a positive integer; balances and deltas SHALL be calculated by the server. Returns linked to a WO SHALL NOT exceed its net issued quantity.

#### Scenario: Excess return
- **WHEN** a return exceeds the unreversed issued quantity remaining for that part and WO
- **THEN** the operation fails without increasing stock

### Requirement: Posted history is immutable
Posted movements SHALL NOT be edited or deleted. A full reversal SHALL reference its original, negate both deltas, retain balance and WO, and restore related quarantine effects atomically. Reversing a reversal or an already reversed movement SHALL fail.

#### Scenario: Receipt already consumed
- **WHEN** reversing a receipt would violate stock invariants
- **THEN** the server returns 409 and preserves both balance and history

### Requirement: Movement visibility and export
Authenticated users SHALL read paginated posted history and details with explicit physical/quarantine deltas, actor, approval, timestamps, references, and reversal links. Search, type, and facility-month filters SHALL be supported. Export SHALL cover the filtered posted dataset, exclude financial fields, and never silently export only one page.

#### Scenario: Filtered export
- **WHEN** the filter matches more rows than the current page
- **THEN** export includes all matching rows or returns an explicit documented size-limit error

### Requirement: Shared Maintenance stock rules
WO-linked operations SHALL use the same approval, availability, and ledger rules. Net usage SHALL derive only from posted issues, returns, and reversals. Missing or ineligible WO references SHALL be rejected; unlinked issues SHALL remain unallocated.

#### Scenario: Pending issue
- **WHEN** a WO has one posted issue and one pending issue
- **THEN** its usage includes only the posted issue

#### Scenario: Future cross-feature failure
- **WHEN** required WO work fails in a coordinated inventory operation
- **THEN** stock and required audit changes also roll back