Failure Modes and Results
RunOperation records a string FailReason when validation/execution fails and logs the operation tag and requested/applied quantities. Subsystem wrappers expose success via pointer/bool and output parameters, not a universal asynchronous result delegate.
| Failure class | Typical cause |
|---|---|
| Initialization | Empty DatabaseArray, missing load or duplicate/None ItemID |
| Routing | Missing Pawn/PlayerState component or mismatched exact identity tag |
| Validation | Invalid requesting Pawn, nonpositive amount, invalid required slot/item |
| Execution | No capacity, missing slot, insufficient quantity or helper failure |
| Unsupported operation | Registered tag without a dispatcher branch |
| UI-only acceptance | Drop accepted locally but server request fails or was never sent |
Partial Success
AddAmount, AddAmountToSpecificInventory and AddToSlot can add a positive partial quantity. Always inspect OutAddedAmount. Returning a master or true does not promise that the requested quantity was fully added.
Failure After Mutation
RemoveFromSlot first removes from the supplied stack, then may fail while resolving a remainder. If the first removal empties the slot, looking up its ItemID afterward fails. Thus false can be returned after items have already been removed. Specific-inventory removal also dispatches through the default database route.
External transfer removes before an assumed target add; its rollback condition uses a value assigned equal to the removed amount, so that branch cannot detect an actual add failure. Merge contains a limited rollback attempt but no universal transactional recovery. Do not retry a failure blindly or promise atomic/no-loss behavior.
Project request validation should reject unsupported/unsafe cases before mutation, track actual authoritative results and refresh presentation on rejection. See Implementation Limits for source locations and exact paths.