Explicit variation-cash futures account method #158

User workflow and ownership

Entry opens signed contracts without exchanging full notional. Marked unrealized PnL=(mark-last settlement/basis)quantitymultiplier; cash changes only for fees, declared variation settlement, funding/external flows. At settlement transfer unrealized variation to cash and reset basis, preserving NAV. Closing realizes only unsettled PnL; avoid double counting earlier settlements.

Backtest owns runtime simulation and actual account exports. Data owns prepared inputs/adjustments, Engineer owns features, Diagnostic owns analytics. Existing Strategy, Engine, LifecycleDispatcher and AccountState remain authoritative. No mandatory new strategy base or Reloaded production dependency.

Current behavior and implementation

method/contract difference. Current interfaces: ContractSpec(multiplier,margin,currency), current signed full-notional fill/account ledger, fixed-margin/leverage controls.

Source locations: accounting/account.py, accounting/policy.py, core/portfolio_ledger.py,
fill/mark paths, instrument metadata, engine events and result exports.

• Add per-instrument futures variation accounting, retaining signed-notional behavior for existing
  users. Equity and futures instruments must coexist in one account with correct NAV treatment.
• Separate notional exposure, unsettled PnL, realized variation, cash, collateral, available funds,
  margin requirements and breaches. Support mark-driven reference payout and declared scheduled
  settlement as different policies. Reads of account views must not create payouts.
• Cover scale-in, flips, partial close, multiple settlements and fees. Share the same account
  effects between quoting, buying-power checks, execution, valuation and result capture.
• Consume dated selections, raw contract prices, notice/expiry/last-tradable metadata and roll
  intent. Execute and retain both roll legs, costs and IDs. Continuous adjusted prices remain
  research inputs. Handle partial/rejected roll legs explicitly rather than fabricating a complete
  roll or assuming generic two-order execution is atomic.
• Preserve end-of-data open positions unless an explicit lifecycle policy closes/settles them.
  Missing terminal prices or lifecycle terms cannot become invented liquidation fills.

Acceptance: multiplier50 and4000-to4010 produces +/-500 variation for one long/short, with no
$200,000 principal cash movement. Margin15000 is collateral, not a fee. Mixed equity/futures NAV,
scale-ins, partial closes and repeated marks reconcile without double counting. A two-contract
volume/OI leadership fixture proves previous-observation selection, next eligible execution, both
leg fills/fees and notice handling. Later volume changes cannot alter earlier contract selection.

Acceptance and independent oracles

• Initial100000, entry4000, multiplier50, one contract, settle4010: longcash100500/NAV100500; shortcash99500/NAV99500, no200000principal movement.
• Initial margin15000/maintenance12000 encumbers15000; entry fee reduces cash/NAV once. At unchanged settlement, zero variation and no duplicate fee.
• Two settlements, scale-in between them, partial close and next-session mark reconcile cash plus residual unrealized PnL; closed contracts cannot receive future variation.
• Insufficient margin, invalid mark/currency or duplicate settlement event cannot partially mutate account state.
• Independent ledger arithmetic first, matched corrected Zipline Future payout profile second. Distinguish Zipline mark-to-market payout frequency from declared exchange daily settlement. Actual Engine fills/account history and built artifact consumer checks, preserve old method regression suite.
• Invalid or ambiguous inputs fail before account/output mutation; unknown information is not fabricated.
• Existing default behavior, actual legacy artifact readers, keys/units, and captured accepted performance samples retain their qualified scope.

Dependencies

• Data dated contracts/settlement declarations for final production workflow; supplied valid fixture supports initial standalone implementation.
• Result metadata/export batch for consumer-visible account semantics.

Source requirements

• Coverage row 170: Pyfolio / Accounting capability and migration boundaries (primary owner Backtest).
• Coverage row 179: Zipline / Futures variation-cash accounting (primary owner Backtest).
• Coverage row 180: Zipline / Dated futures, roll execution and expiry/notice lifecycle (primary owner Backtest).

Evidence and completion

Retain failing-base/passing-fix public Engine evidence for defects; independent arithmetic and matched native reference configurations for new behavior. Test actual installed producer-to-consumer workflows, not reconstructed account objects. All applicable final-head source, type, coverage, package, security, platform and strict documentation checks must pass before ordinary guarded merge. Missing essential workflows remain unfinished. No release or deployment is included.

Premises: none - This projection preserves accepted implementation requirements and explicit independent acceptance oracles; it introduces no untested factual assumption as a design prerequisite.

Closes: none
Advances: none

AI assistance: This implementation specification was prepared with OpenAI Codex using source inspection, retained Engine reproductions and the accepted maintainer-reviewed cross-library scope. The implementing maintainer remains responsible for review and executed evidence.

Plan reference: successor implementation projection, Issue 5; batch futures-account.