Raw corporate-action position/order/cash ledger #157

User workflow and ownership

Immutable event ID/revision, instrument ID, action kind, available_at, effective_at, ex/entitlement/record/payment instants or explicit session labels, source currency and price/share basis. Split ratio is new shares / old shares. Retain entitlement independently of later position changes. At a shared instant process eligibility/actions before dependent valuation/order handling according to a documented deterministic sequence.

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

missing capability. Current interfaces: Data apply_corporate_actions/apply_splits/apply_dividends for preparation only, Engine/Broker current raw price/order path.

Source locations: incoming-event validation in the feed boundary, engine event ordering, broker
orders/positions, account ledger and result persistence. Reuse the current adjustment-preparation
route without confusing it with live action processing.

• Consume validated raw split/reverse-split, cash-dividend, stock-distribution and cash/security
  conversion events with IDs, ratio direction, availability and effective/entitlement/payment
  times. Preserve payment entitlements after an intervening trade or position close.
• Adjust position basis, pending/partially filled order quantities and limit/stop levels through
  one deterministic event application. Handle long and short liabilities and fractional terms.
• Separate native declared economic terms from explicit Zipline-compatible rounding,
  cash-in-lieu and dividend-recognition policies. Invert legacy split ratios exactly once.
• Validate basis/provenance before execution so adjusted prices plus raw events cannot silently
  double count. Retain idempotency/revision rules and no partial mutation on invalid events.

Acceptance: 10 shares at100 become20 at50 on a declared2:1 split, with cash9000 and NAV10000;
the reverse, shorts and partial-order cases conserve the declared exposure. A $1 entitlement for
10 eligible shares pays $10 once at payment, even after those shares are sold. Test ex-to-pay NAV
under both explicit recognition methods, fractional cases, stock payments and conversion legs.
Use native reference behavior where demonstrated and independent oracles for broader merger terms.

Acceptance and independent oracles

• 2:1 split:10 shares100 ->20 shares50, cash9000 andNAV10000; reverse split is inverse, for long and short.
• One-dollar entitlement on10shares -> receivable10 then cash credit10 at payment; short gets payable10 and cash debit10. Ex-date is not automatic payment.
• Pending10share limit100 with4filled has6remaining before split; after2:1, position8 and remaining12 atlimit50; split conserves exposure and order/lot lineage.
• Fractional distribution, merger with cash/security legs, duplicated/revised event and invalid currency/ratio have independent conservation and no-partial-mutation assertions.
• Data producer contract test and Backtest consumer test on identical fixture; actual Engine action scenarios, built artifact round trips, matched Zipline3.2.0 native ledger for supported terms plus independent cash/quantity oracles. Reference disagreement requires investigation, not forced equality.
• 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 validated raw event and basis contract, including identity and availability.
• Producer result tables for action receivables/ledger visibility; not a prerequisite to beginning event-contract tests.

Source requirements

• Coverage row 170: Pyfolio / Accounting capability and migration boundaries (primary owner Backtest).
• Coverage row 177: Zipline / Raw split/dividend/merger/stock-distribution ledger (primary owner Backtest).
• Coverage row 178: Zipline / Price adjustment basis and causal history (primary owner Data).
• Coverage row 181: Zipline / Stable IDs, dated symbols, lifetimes and delistings (primary owner Data).

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 4; batch corporate-actions.