The bounded set of generic reason-code atoms produced by PaperEx.Engine and the default execution model.

Reason codes are intentionally short atoms (or short strings) — the same value space is used for analytics, dashboards, and downstream alerting. Long error detail belongs in PaperEx.Execution.metadata, never in the reason field.

Adapters may add their own bounded reason codes via PaperEx.Adapter.reason_codes/0. Adapter-specific codes should be short atoms namespaced informally to the adapter (e.g. :polymarket_neg_risk_blocked) so a multi-adapter consumer can filter them.

Generic engine reason codes

• :insufficient_cash — the order requires more cash than the portfolio has free.
• :insufficient_position — a sell exceeds the position size held.
• :max_order_notional — the order would exceed the engine's per-order notional cap (PaperEx.Engine config).
• :max_position_size — the resulting position would exceed the per-position size cap.
• :limit_not_crossed — a :limit order's price did not cross the book.
• :no_liquidity — the relevant side of the book was empty or could not supply enough size.
• :adapter_rejected — an adapter callback declined the order (e.g. tick-size mismatch).
• :duplicate_position — a duplicate-policy guardrail rejected a same-market same-strategy second open.
• :shorts_disallowed — the portfolio config disallows opening short positions and the order would have done so.
• :market_resolved — the market resolved to a final outcome. Used on the :closed executions PaperEx.Engine.resolve_market/4 appends for each resolved position, and on the :cancelled executions it appends for pendings that can no longer fill.
• :cancelled_by_caller — default :reason on the :cancelled Execution that PaperEx.Engine.cancel_pending/3 appends when a caller cancels a resting pending remainder (overridable via the :reason opt).
• :pending_intent_missing — PaperEx.Engine.advance_pending/3 could not reconstruct the pending order's intent from its recorded metadata (e.g. a required field such as :market_id, :side, or :limit_price was absent), so the remainder could not be re-simulated.

Future engine phases may extend this list. Removing or renaming a code is a breaking change.