# `PhoenixKitWarehouse.CommittedQuantities`
[🔗](https://github.com/BeamLabEU/phoenix_kit_warehouse/blob/0.4.0/lib/phoenix_kit_warehouse/committed_quantities.ex#L1)

Computes, per source document, how much quantity per item has already been
committed to non-deleted downstream documents referencing it — used so that
selecting the same source into a second (or later) document only adds what's
still outstanding, instead of duplicating the full original quantity.

# `compute`

Returns `%{source_uuid => %{item_uuid => Decimal}}` — for each uuid in
`source_uuids`, the quantity already committed against it, summed across all
non-deleted rows of `schema` whose `source_refs` contain a ref whose `"type"`
is in `ref_types` and whose `"uuid"` matches.

For refs recorded with a `"lines"` breakdown, uses that breakdown exactly.
For legacy refs without one, falls back to attributing the document's own
aggregate `lines` (keyed by `line_quantity_field`) to that ref — a safe
overcount for the rare pre-existing multi-source merge.

`opts`:
  * `:status` — when given, only rows of `schema` whose `status` field
    equals it are considered (in addition to the always-applied
    `is_nil(deleted_at)` filter). Omit (the default) to consider every
    non-deleted row regardless of status.

    Leave this unset for "avoid double-importing the same source into two
    documents" call sites (the common case) — that computation must
    include the document's own not-yet-posted draft (it's what makes a
    second import into the *same* still-draft document net out instead of
    duplicating). Pass `status: "posted"` only for call sites computing an
    actual on-hand/reservation effect, where a draft downstream document
    hasn't happened yet and so must not be netted out.

# `merge_ref`

Merges a `{ref_type, source_uuid}` ref carrying `imported_lines`
(`%{item_uuid => Decimal}`) into `existing_refs`. If a ref for that
`{ref_type, source_uuid}` pair already exists, its `"lines"` map is summed
with `imported_lines` in place — never skipped, never replaced — so the
ref's `"lines"` always reflects the running cumulative total ever pulled
from that source into this document.

---

*Consult [api-reference.md](api-reference.md) for complete listing*