paper_ex

# Changelog

## 0.8.0 - 2026-07-25

### Added

- **`decide/2` may now cancel resting orders.** The callback can
  return `{orders, cancels, state}` (a 3-tuple) in addition to the
  existing `{orders, state}`; `cancels` is a list of `:order_id`s of
  resting pending remainders to cancel before the new `orders` are
  placed. Backward compatible — the 2-tuple form is unchanged and
  every existing strategy keeps working; a runner distinguishes the
  two by tuple arity. This is what lets a strategy *move* a resting
  quote (cancel the stale one, place a fresh one) instead of only
  ever adding orders — the prerequisite for genuine two-sided market
  making. New `PaperEx.Strategy.decision/0` and `cancel_ref/0` types.
- **Optional `cancels?/0` callback** — a strategy returns `true` to
  declare it uses the cancel form, so a host can refuse unsafe
  pairings up front (e.g. a runner that mirrors orders to a venue it
  cannot yet cancel on). Optional, defaults to `false`, fully
  backward compatible.

## 0.7.0 (unreleased)

### Added

- **`PaperEx.Strategy` behaviour** — the strategy contract
  (`init/1` validation, pure `decide/2` over
  `%{instrument_id, snapshot, portfolio}` with threaded state),
  promoted from the `polymarket_bot` reference app once multiple
  strategy families (resting-bid, copy-trade, scanner) proved the
  abstraction. Exchange-agnostic: contexts may carry extra
  host-specific keys; strategies match only what they need.
  Includes `implemented_by?/1`. 4 new tests.

## 0.6.0 (unreleased)

### Changed

- **GTC rest-on-miss** (Codex review finding). Under
  `pending_remainder: true`, a `:limit` order that misses entirely
  (`:limit_not_crossed` or `:no_liquidity`) now **rests as a
  full-size pending remainder** instead of evaporating — which is
  what GTC means. Previously only *partial* fills rested, so a
  resting-order strategy would re-submit the same intent every
  tick. The `:missed` execution is still recorded (the attempt is
  auditable); the new `:pending` sits alongside it and is advanced
  /cancelled through the existing lifecycle. Without the flag, and
  for `:market` orders, behavior is unchanged. 5 new tests.

## 0.5.0 (unreleased)

### Added

- `PaperEx.Engine.resolve_market/4` — prediction-market resolution.
  Closes every open position on a market at its final outcome
  (`:won` → `:payout_per_share`, default `1.0`; `:lost` → `0.0`),
  computes realized P&L, credits/debits cash (synthetic shorts buy
  back at the final price), applies an optional `:win_fee_rate` to
  winning long payouts, cancels open pending remainders on the
  market, and appends `:closed` / `:cancelled` executions with the
  bounded reason `:market_resolved`. Returns
  `{:ok, portfolio, %{closed: [...], cancelled_pending: [...]}}`.
- `PaperEx.Valuation` — pure mark-to-market valuation of open
  positions against caller-supplied snapshots.
  `open_position_value/3` prices longs at best bid and shorts at
  best ask (`:conservative`, default) or both at `:midpoint`,
  returns a net liquidation value with a per-position breakdown,
  and refuses partial totals (`{:error, {:unpriced, ids}}`) rather
  than silently omitting unpriced positions.
- `:market_resolved` added to `PaperEx.ReasonCodes.engine_codes/0`.
- 23 new tests covering long/short resolution for both outcomes,
  win-fee semantics, custom payouts, pending cancellation on
  resolution, market scoping, multi-strategy resolution, ledger
  effects, outcome validation, and the full valuation matrix
  (conservative/midpoint pricing, empty book sides, missing
  snapshots, netting, portfolio input, closed-position exclusion).

### Changed

- Engine moduledoc documents the two position-exit paths (selling
  and resolution); the "P&L on close not implemented" caveat is
  gone.
- `resolve_market/4` validates `:payout_per_share` and
  `:win_fee_rate` (non-negative numbers; `ArgumentError` otherwise)
  — a negative value would silently corrupt cash/P&L (Codex review
  finding).
- The exit-side P&L convention is now documented explicitly and
  pinned by a test: `Position.pnl` is `(exit - entry) * shares`
  minus exit-side fees only, on both the sell-close and resolution
  paths. Opening fees hit cash at open time and are deliberately
  not re-subtracted into `pnl`.

## 0.4.0 (unreleased)

### Added

- `PaperEx.Engine.open_pending_remainders/1` — public helper
  returning the currently-open pending remainders of a
  `PaperEx.Portfolio` or a raw `[PaperEx.Execution]` list, in
  ledger order. This is now the single source of truth for the
  open-pending rule (latest pending per `order_id`; cleared by a
  later `:cancelled` for that id or a later `:filled` tagged
  `metadata.resolves: {:pending_remainder, order_id}`; unrelated
  fills do not clear).

### Changed

- `cancel_pending/3` and `advance_pending/3` internals now derive
  open pendings through `open_pending_remainders/1` instead of a
  private duplicate. Behavior is unchanged — the private
  `find_open_pending/2` and `open_pendings_for/2` delegate to the
  public helper.

## 0.3.0 (unreleased)

### Added

- `PaperEx.Engine.advance_pending/3` — pure function that walks
  open `:pending` executions matching a fresh `MarketSnapshot`'s
  `instrument_id` and tries to resolve each remainder. Returns
  `{:ok, updated_portfolio, results}` where `results` is a list of
  `{pending_execution_id, outcome}` tuples preserving ledger order.
  Outcomes:
  - `{:filled, filled_execution}` — full remainder filled.
  - `{:partial, filled_execution, new_pending}` — partial fill;
    `new_pending` has the same id with a reduced `remaining_size`.
  - `{:still_pending, pending}` — no cross / no liquidity. No
    ledger churn.
  - `{:skipped, reason, skipped_execution}` — guardrail rejected
    (`:shorts_disallowed`, `:insufficient_position`,
    `:insufficient_cash`, `:adapter_rejected`,
    `:pending_intent_missing`).
- 18 new `paper_ex` tests covering: empty / different-market
  shortcuts; no-cross and no-liquidity → still pending; partial
  advance (remaining_size reduced, position grown); full advance
  (closes pending so `cancel_pending/3` reports `:pending_not_found`);
  deterministic ordering across multiple pendings; sell-shorts
  guard from a held=0 setup; `allow_shorts: true` opens a new
  short; `:insufficient_position` from a drained long;
  `:insufficient_cash` with strict and `allow_negative_cash: true`
  configs; missing-adapter and legacy-pending (no `:side`)
  fallbacks; `apply_order/4` return shape unchanged; ledger /
  `find_open_pending/2` semantics after partial vs full advance.

### Changed

- `:pending` remainder metadata now carries `:side`, `:limit_price`,
  and `:order_type` so `advance_pending/3` can reconstruct the
  order intent without retaining the original `Order` struct. This
  is additive — old callers that read other metadata keys are
  unaffected. Pendings created before this version are advanced as
  `{:skipped, :pending_intent_missing, …}`.
- `find_open_pending/2` (private) now also clears the open pending
  on a later `:filled` execution tagged with
  `metadata.resolves: {:pending_remainder, order_id}`. The
  pre-existing behavior of NOT clearing on the initial filled-then-
  pending sequence from `apply_order/4` is preserved (the initial
  filled lands BEFORE the pending in the ledger and so its acc
  precedes the pending).
- Engine moduledoc rewritten to document `advance_pending/3` and
  the extended pending-metadata contract.

## 0.2.0 (unreleased)

### Added

- **Opt-in pending-remainder policy.** `PaperEx.Engine.apply_order/4`
  now accepts `:pending_remainder` in the config keyword. When set
  to `true` and a `:limit` order partially crosses, the engine
  appends a `:pending` `PaperEx.Execution` to the portfolio's
  ledger alongside the existing filled execution. The `:pending`
  entry has id `{:pending_remainder, order.id}` and metadata with
  `remaining_size`, `filled_size`, `market_id`, `strategy`, and
  `mode`. `:market` orders are FAK and never produce pending
  entries.
- `PaperEx.Engine.cancel_pending/3` — pure helper that resolves a
  pending remainder by appending a `:cancelled` `Execution` to the
  ledger. Accepts `:reason` and `:metadata` options. Returns
  `{:ok, portfolio, cancelled_execution}` or
  `{:error, :pending_not_found}`. Cash and positions are not moved
  (pending never moved them either).
- 16 new tests covering: default behavior (pending not recorded
  when policy off), pending recorded on partial limit fill with the
  documented metadata shape, market FAK never records pending,
  fully-filled limit orders never record pending, `cancel_pending`
  honoring caller `:reason` and `:metadata`, idempotency boundary
  (can't double-cancel), and return-shape stability
  (`apply_order/4` still returns `{portfolio, execution}` and the
  primary execution is the filled one).

### Changed

- `PaperEx.Engine.apply_order/4` adapter dispatch now wraps
  `function_exported?/3` checks with `Code.ensure_loaded?/1` so
  adapters living in dependency apps that the BEAM has not yet
  auto-loaded resolve correctly.
- Engine moduledoc rewrites the "what this engine does NOT do"
  section to reflect that pending remainders are now first-class
  for `:limit` orders.

## 0.1.0 (unreleased)

Initial scaffold of the generic exchange-agnostic paper trading
engine. Pure functional core: structs, an adapter behaviour, and a
single state-transition function. No HTTP, no database, no Polymarket
dependency.

### Added

- `PaperEx` top-level module with `version/0` and a moduledoc that
  records the two-modes design constraint (research vs live-mirror)
  carried over from the production source.
- Core domain structs:
  - `PaperEx.Order` — buy/sell request keyed by `market_id`, with side,
    type (`:limit | :market`), size, price, optional strategy tag,
    and a free-form metadata map.
  - `PaperEx.Execution` — first-class attempt record. Status is one
    of `:filled | :missed | :skipped | :pending | :cancelled | :closed`,
    so misses and skips are peer values, not absorbed into "no trade".
    Carries an optional list of `PaperEx.Fill` structs and
    aggregates (`vwap/1`, `total_size/1`, `total_fees/1`).
  - `PaperEx.Position` — open or closed paper position with entry,
    optional exit, side, shares, strategy tag, and metadata.
  - `PaperEx.Portfolio` — top-level container for starting balance,
    current balance, peak balance, open positions, history, the
    execution-attempt ledger, and stats.
  - `PaperEx.Fill` — atomic fill at one price level, with notional
    and cost helpers.
  - `PaperEx.Instrument` — normalized exchange-agnostic market id
    with display fields and optional tick size.
  - `PaperEx.MarketSnapshot` — order-book snapshot for one
    instrument with best-bid/ask, midpoint, and spread helpers.
  - `PaperEx.ReasonCodes` — bounded set of generic engine reason
    atoms.
- `PaperEx.Adapter` behaviour with required `normalize_instrument/1`
  and `normalize_snapshot/2`, and optional `normalize_fill/2`,
  `simulate_fill/3`, `fee/2`, and `reason_codes/0`.
- `PaperEx.Engine.apply_order/4` — pure state transition: pre-flight
  guardrails, adapter-driven fill simulation, fee passthrough, VWAP
  fills, open/merge/close position bookkeeping, history append,
  ledger append. Configurable via a keyword list:
  `:adapter`, `:adapter_opts`, `:max_order_notional`,
  `:max_position_size`, `:allow_shorts`, `:allow_negative_cash`,
  `:duplicate_policy`, `:mode`.
- `PaperEx.MockAdapter` in `test/support` — minimal worked example
  implementing every callback (required and optional).
- 150+ tests covering domain struct validation, adapter behaviour
  conformance, mock-adapter normalize/simulate/fee/reason paths,
  engine happy paths (buy, sell, partial close, multi-level VWAP),
  every guardrail skip (insufficient cash, insufficient position,
  shorts disallowed, max order notional, max position size,
  duplicate position), limit miss, no-liquidity miss, adapter-absent
  skip, fees on buy/close, every code path records exactly one
  execution, and `:mode` metadata round-trip.

### Deferred

- Resolving `:pending` resting orders across snapshots.
- An optional GenServer wrapper for long-running paper portfolios.
- Mark-to-market P&L updates triggered by snapshots alone.
- The first-party Polymarket adapter — lives in the separate
  `paper_ex_polymarket` package per the workspace package map.