# Indirect Goods Upgrade — Phase 8 Consumption, Damage and Expiry Integration Completion

Completed: 11 July 2026

## Outcome

Indirect consumption and on-site disposal now use the same fulfillment-allocation provenance as issues and returns. A quantity can no longer be both consumed and returned.

## Schema additions

Added `indirect_goods_consumption_allocations` to link each consumption record to:

- fulfillment;
- fulfillment allocation;
- project inventory row;
- exact consumed quantity.

Extended `indirect_goods_consumption` with:

- project inventory reference;
- division reference;
- disposition status;
- evidence file;
- disposal timestamp.

## Live consumption behavior

`IndirectGoodsConsumptionController` now creates the consumption record and calls `IndirectGoodsConsumptionService` in one database transaction.

The service:

1. locks project inventory;
2. validates available project quantity;
3. selects matching outstanding fulfillment allocations by project, item and invoice;
4. excludes quantities already returned, consumed or transferred;
5. increments allocation and fulfillment consumed quantities;
6. creates consumption-allocation provenance rows;
7. reduces project inventory and increments project consumed quantity;
8. records disposition status and timestamp;
9. creates a real project consumption movement;
10. rebuilds the indirect division summary.

## Damage and expiry rules

The consumption screen now explicitly distinguishes physical returns from on-site disposal:

- Physically returned damaged, expired or unused goods must use **Indirect Returns to FOC**.
- `damaged`, `expired` and `written_off` consumption types mean the goods were disposed at the project site.
- Evidence files are required for written-off, damaged and expired on-site dispositions.
- On-site disposal does not create FOC inventory.
- Physical return does not create consumption.

This makes return and disposal mutually exclusive at fulfillment-allocation level.

## Historic backfill

Added command:

`indirect-goods:backfill-consumption-links`

It requires `--dry-run` or `--commit` and is idempotent.

Results:

| Metric | Result |
|---|---:|
| Historic consumption records | 1 |
| Links created | 1 |
| Linked quantity | 2.0000 |
| Exceptions | 0 |
| Second-run new links | 0 |
| Reconciliation variance | 0.0000 |

## Verification

### Rolled-back live smoke test

One unit was consumed from project inventory using outstanding historic allocation provenance.

Verified during the transaction:

- disposition: consumed;
- consumption links: 1;
- warehouse quantity change: 0.00;
- project quantity change: -1.00;
- project consumed change: +1.00;
- returned-to-FOC change: 0.00;
- FOC change: 0.00;
- movement linked to fulfillment and project inventory;
- reconciliation variance: 0.0000.

The test was rolled back and all baseline quantities/counts were restored.

### Final reconciliation

| Metric | Result |
|---|---:|
| Consumption records | 1 |
| Consumption allocation links | 1 |
| Consumption quantity | 2.00 |
| Linked consumption quantity | 2.0000 |
| Unlinked consumption records | 0 |
| Negative stock rows | 0 |
| Over-accounted allocations | 0 |
| Reconciliation variance | 0.0000 |

## Phase gate

Phase 8 is complete. Phase 9 may consolidate the unified Material Issue UI, issue details and print documents around the now-complete warehouse, direct-delivery, FOC, return and consumption domain flows.