# Inventory Valuation / Weighted Average Cost v24

## Purpose

Quantity alone is not sufficient for inventory.

v24 adds valuation so the platform can answer:
- how many units are on hand?
- what is their total carrying value?
- what is the current weighted-average unit cost?
- what cost was consumed by an outbound movement?

## Weighted average

For inbound stock with a supplied unit cost:

new value =
existing value + (incoming quantity × incoming unit cost)

new weighted average =
new value / new quantity

Example:

10 units @ 5 = 50
10 units @ 7 = 70

Total:
20 units
value = 120
weighted average = 6

## Outbound valuation

Outbound stock always consumes the current weighted-average cost.

If current average is 6 and 4 units leave:

quantity delta = -4
value delta = -24
unit cost snapshot = 6

The average remains 6 until new inbound stock changes it.

## Movement cost snapshot

Inventory movements now optionally persist:
- unit_cost_amount
- value_delta

These values are immutable with the movement.

## Valuation balance

`inventory.valuation_balances` is an operational/rebuildable valuation projection by:
- tenant
- warehouse
- variant
- optional variant unit

It stores:
- quantity_on_hand
- inventory_value
- weighted_average_cost

The immutable movement ledger remains the primary historical source.

## Existing stock

Stock that existed before v24 is backfilled with:
- existing quantity
- zero historical value
- zero historical average cost

This is intentional because v24 cannot invent historical acquisition costs.

A future opening-valuation workflow may establish verified opening values.

## Sale cost snapshots

When completed sales are posted to inventory, the outbound movement's cost is captured into:

`inventory.sale_cost_snapshots`

This avoids mutating immutable `sales.sale_lines`.

Each sale-line cost snapshot stores:
- quantity
- weighted-average unit cost at posting time
- total cost

This becomes the basis for gross-profit reporting.

## API

GET /api/v1/inventory/valuations

## Next

v25:
- purchase receiving foundation
- supplier receipt cost
- purchase_receipt inventory movement
- weighted-average cost update from supplier receipts
- basis for 3-way matching later