%PropertyUnitLedger.Event{} requires nonempty id and unit_id, an atom kind from the fixed vocabulary and a UTC DateTime at. Optional source is informational. No timestamps are inferred. :reserve additionally requires a nonempty reservation_id and strictly later UTC expires_at. :release and :expire require a reservation ID. A sale of reserved inventory must supply the matching ID.
| Current state | Event | Result |
|---|---|---|
| Unknown | register | available |
| Available | reserve | reserved |
| Available | sell | sold |
| Available | withdraw | withdrawn |
| Reserved | release with matching ID | available |
| Reserved | expire at/after deadline, matching ID | available |
| Reserved | sell before deadline, matching ID | sold |
Other transitions fail. Registering a known unit with another event ID fails. IDs are global within a ledger; use source prefixes where upstream systems have overlapping IDs. Idempotency compares the whole event, including source metadata. Retrying a corrected event under an accepted ID is a conflict; choose a new meaningful event ID.
Error atoms are machine-readable: invalid_event, invalid_event_id, invalid_unit_id, invalid_event_kind, invalid_event_time, missing_reservation_id, invalid_expiry, expiry_not_future, event_id_conflict, unknown_unit, out_of_order, already_registered, reservation_mismatch, not_yet_expired, reservation_expired, invalid_transition.