docs: clarify corporate-action and futures cash migration boundaries - #154

Purpose

Closes #153. Clarify the existing migration, accounts and data references without changing runtime behavior. Reviewed head: b678e7010c43176684711dcbfb0b1293f343a405.

The perpetual-contract tutorial previously described a generic futures accounting convention. It now names Backtest's full-notional cash model. The migration guide distinguishes prepared prices from raw corporate-action entitlement/share ledgers, and contract P&L/margin from variation cash. It also states the retained CME input's missing dated-chain/roll-map limitation without implying that Zipline lacks futures support.

Evidence

• Actual public Engine workflows on main e74bed7 and calendar source 391cc8a reproduce long/short cash of -$100,000/$300,000 and equity of $100,500/$99,500 for the declared one-contract 4,000-to-4,010 move with multiplier 50. The behavior agrees with the existing notional ledger. No runtime defect or terminal-equity parity claim is inferred.
• Discovery columns named split_ratio/cash_dividend are not advertised event APIs. They do not trigger raw share/cash adjustments. The docs state the capability boundary rather than invent an API.
• The eight runnable examples across all three changed pages passed; 49 direct API calls checked. The unchanged migration example remains runnable.
• Ordinary applicable commit hooks, strict rendered docs, 9,024 content links, 35 external destinations and exact source identity passed at b678e70. The CME URL failed the actual link checker with HTTP403; the replacement CFTC primary reference passes the unchanged checker.
• Applicable hosted checks are still queued/pending. Keep draft until they pass; no merge or deployment is claimed.

Reference methods were checked against primary CME/CFTC material and the pinned Zipline 3.1.1 ledger source. The public account guide links the accessible CFTC definition. Zipline marks futures payouts during portfolio valuation; the prose does not equate that cadence with daily exchange settlement.

Scope and AI assistance

Only three documentation files change. No event-processing API, settlement mode, default, dependency, performance report, redirect or publication is changed. Implementing missing raw-action or settlement workflows remains a separate capability decision; this documentation does not implement them.

Codex inspected source/primary references, executed the public workflows and drafted the correction. This is maintainer-directed AI assistance, with actual checks distinguished from pending checks.