feat: add explicit futures variation-cash accounting - #167

Owning issue

Closes #158. Advances #159 and #156. Dated roll execution and final migration closure remain separate work.

Outcome

Add explicit per-instrument futures variation cash to the existing Engine, Broker and AccountState. Existing contracts retain signed-notional accounting. Choose scheduled settlement events or mark/fill-driven payout. Account observations distinguish liquidation, notional, initial/maintenance margin, available funds and unsettled variation.

The same variation-fill rule now governs execution, submission reservations and queue projections. Schema 6 artifacts retain actual payout records and account observations, including combined corporate actions and benchmarks. Schema 2-5 readers remain covered. No legacy production dependency is added.

Regression and reference evidence

• Existing fixed-margin validation ignored a declared $15,000 requirement in favor of $200,000 full notional. A public Engine failure on base 66b2134 now passes.
• Public helper forwarding, liquidation versus exposure, atomic mark groups, unpaid-dividend availability and callback rollback have retained failing-base/passing-fix checks.
• On previous PR head 04850b3, the expanded public financial suite has 15 failures and 50 passing controls. Reservation/simple-cash paths spent futures principal; scheduled scale/close projections lost variation basis. The repair shares the actual fill transition, reserves fees once, refreshes from actual observation state and preserves rollback.
• Eight captured actual Zipline Reloaded 3.2.0 runs cover long, short, close and scale/partial/flip, each with zero or fixed per-future fees. Complete cash, NAV, position basis, mark and fill traces match exactly without widened tolerances. Actual installed Data snapshot and contract-preparation workflows are included.

Compatibility and method choices

New ContractSpec fields are keyword-only and opt-in. Scheduled exchange settlement and mark-driven reference payout remain distinct. Reads never pay; settlement marks do not become execution quotes; margin is collateral rather than a fee. The single cash account does not convert currencies. The callback adapter retains its explicit unconstrained entry profile; native Engine supports constrained margin. End-of-data does not invent liquidation fills.

The continuous-root CME workload still lacks a dated chain/roll map for the Zipline comparison. This PR makes no universal futures-parity or new speed claim. The runnable futures-accounting guide documents the next-version source boundary, absent from published 0.1.12 and the preserved pending 0.1.13 candidate.

Checks actually run

• Source 5e39dd80: full suite: 3,086 passed,85 optional skips,5 deselected. Its 14 source-bound evidence failures were resolved through fresh reports; all 67 targeted evidence/compatibility checks then pass. Every global and critical coverage threshold passes.
• Focused financial, default, rollback and ownership checks: 327 passed,8 optional skips. Ruff, formatting,ty, compatibility generation and normal hooks pass.
• Isolated 5e39 wheel: 261 passed with warnings as errors, including actual installed Data and all 16 captured-reference variants.
• Fresh Backtest: 66 synthetic and 17 production comparisons pass against hash-verified frozen reference outputs. Reference frameworks and licensed authentication were not rerun.
• All accepted publication timing samples remain unchanged, measurement SHA256 2764a504d315ca55a1bc077073c138de959be647816b651a819d4bde21dfb4e1. The prior 7dc bounded ETF/CME source diagnostics and explicit follow-up source review support reuse; they are not relabeled as 5e measurements or new gains.
• Strict docs build, executed source/installed examples, 11,554 rendered links/44 external destinations and version/source identity pass at their recorded revisions. Final-head hosted documentation checks remain required.
• Wheel/sdist builds and artifact validation pass; the earlier 7dc independent rebuild is byte-identical. Runtime dependency audit has no findings; source security scan is refreshed for the repair.
• Every applicable exact-head hosted supported-platform, compatibility, coverage, docs, security and package gate. Ordinary guarded merge waits for these checks.

AI assistance and release

OpenAI Codex assisted with implementation, reference capture, tests, documentation, source review and this PR text. Review used original source, independent account arithmetic and the actual public workflows above. Final-revision gates remain required. No release, tag, publication or deployment is included.