feat: add causal raw corporate-action accounting - #166

Owning issue

Closes #157. Advances #156; futures variation cash, dated rolls and final installed migration journeys remain separate accepted batches.

Outcome

Apply explicit raw split, dividend, stock distribution and cash/security conversion facts through the existing DataFeed, Engine, broker and account ledger. Native declared terms recognize receivables; the explicit zipline_3_2 method retains qualified rounding/payment recognition. Preserve raw observations and quote timestamps, original fills and requested order quantities. Adjust pending/partial orders and release covered short collateral. Converted identities reject new orders.

Persist action and entitlement lineage with observed receivables in schema 5, including combined benchmark artifacts. Older artifacts remain readable and unavailable action history stays unavailable. Add a complete runnable corporate-action guide, navigation and executable documentation checks.

Regression and correctness evidence

• Missing-action base 1ac18708a289b54a5e8a4a5c7ac0adac9bac34ea: 13 valid public Engine workflows failed on the missing DataFeed API. Independent split/entitlement/conversion arithmetic and passing controls are retained.
• Base a5c84936e3f9216c090a8a5c7f2a507d91a51212: convenience-runner action forwarding, physical entitlement precedence and effective conversion before strict expiry validation each failed through public workflows. The corrected Engine tests pass, including actual installed Data identity selection.
• Real Engine-produced action/benchmark artifacts exposed the schema-5 reader incompatibility. A real Parquet writer fault exposed an uncaught non-object JSON exception. Both now fail with the documented artifact error or complete the valid round trip, as appropriate.
• Published Zipline Reloaded 3.2.0, source cf649ac06fddce76f6caa2403cd8494ac84f72ad, and actual ML4T Data c3b9db80a66397420fb27adeccc762559dd41e07 snapshots cover 20 long/short split, reverse/partial-order, cash-after-sale and own/cross-stock scenarios. Compare full closing orders/positions/fills/cash/NAV. Sixteen mechanical-price cases also match premarket traces. Four boundary cases distinguish ex/record dates, own-share delivery and extra price moves.
• Original daily premarket valuation reads the same-day close. An ex-day-close-only $7 change moves its early mark $7. Backtest preserves the causal adjusted previous mark. This investigated reference difference is documented and tested rather than reproduced as lookahead.
• All 66 synthetic and 17 production correctness pairs pass with published Specs 0.2.0. Immutable reference ledgers are hash-verified and reused; reference engines and licensed authentication were not rerun.
• Accepted performance records and measurement dates are unchanged. Source review plus alternating ETF/CME default-path diagnostics against the measured source support no material impact. No speed claim is made for action-enabled runs.

Verification

• Public failing-base/passing-fix controls and independent financial oracles
• Ruff, format, ty and ordinary full pre-commit hooks
• Full source suite: 3,014 passed, 56 optional skips, 5 benchmark deselections; 90.82% statement / 81.22% branch coverage and every critical-module threshold passes
• Actual final wheel/sdist: reproducible bytes, exact package manifests and Twine checks
• Isolated installed final-wheel workflows: 265 passed, warnings treated as errors, including all 20 actual Data preparation-to-Engine cases
• Fresh correctness, source/dependency security scans with no exception or finding
• Executable docs, strict MkDocs, 11,307 rendered content links / 44 external destinations, exact version/source identity
• Final current-head hosted supported-platform qualification: 42 successful checks and one inapplicable exception-validator skip

Final reviewed head is 66b213482431f4cf68e0a65639d128511eade7a3. Full source/coverage and numerical runs were collected at e7995b427dfd65847b669a0d1f1326f5531dd1eb; every package source file is unchanged at the final head. All 104 non-version Python modules in the final wheel are byte-identical to that qualified wheel. The final commit adds real producer contract tests and refreshes generated evidence/docs; its full installed suite and exact docs identity were checked again. Hosted CI qualified this exact head; ordinary squash merge 9493bcb completed on 2026-10-22T00:14:37Z.

Compatibility and publication

This is the next-version source boundary, not a modification of the preserved 0.1.13 release candidate. Native no-action account defaults remain unchanged. Raw actions require declared raw input basis, publication, currency and economic terms; no terms or executable quotes are invented. Data owns normalization and prepared facts. No Reloaded package is a production dependency. General merger/tax-lot/FX parity is not claimed.

No release, tag, publication or deployment is included.

AI assistance

OpenAI Codex assisted with implementation, regression and contract tests, documentation, original-framework captures and this PR text. The source diff, financial semantics and actual executed evidence were reviewed in the owning maintenance session. Accountability remains with the maintainer.