# ThreeWayMatchEvent

## Description

ThreeWayMatchEvent is an append-only history table that records the matching relationship between a purchase bill line and an inventory execution line used as goods-receipt evidence. Each row represents one matching event: which bill line was matched to which InventoryExecutionLine, for how much quantity, when, and by whom. The table is never updated or deleted — unmatch operations are recorded as new rows (e.g. with negative or zero matchedQuantity), preserving a full audit trail.

This table exists because the purchase-order-line reference on PurchaseBillLine is nullable and inventory receipt evidence is held by InventoryExecutionLine source references. Even when both sides resolve to the same purchase-order line, the indirect PO-line-based relationship between bills and posted goods-receipt lines is insufficient for audit. ThreeWayMatchEvent provides the explicit evidence of "which invoice line was matched to which inventory execution line" that ERP audit and reconciliation require.

## Domain Model Definitions

### Model type

AppendOnly

### Command Definitions

- [matchPurchaseBill](../command/MatchPurchaseBill.md) - Creates ThreeWayMatchEvent records when matching bill lines to posted goods-receipt inventory execution lines

### Query Definitions

None

### Models

- ThreeWayMatchEvent

### Invariants

- Every event must reference exactly one PurchaseBillLine and one InventoryExecutionLine
- Matched quantity must be recorded (may be negative for unmatch events)
- Rows are immutable once created; corrections are expressed as new events
- matchedAt records the timestamp of the matching operation
- matchedBy optionally records the user or system that performed the match

### Relationships

- **References PurchaseBillLine**: `purchaseBillLineId` identifies which bill line participated in the match
- **References InventoryExecutionLine**: `inventoryExecutionLineId` identifies the posted goods-receipt line whose quantity was consumed
- **No direct PO reference**: The purchase order context is derivable from the referenced bill line and InventoryExecutionLine; storing it here would be redundant and risk update inconsistency
