Repository navigation
Prepare validated corporate-action facts and explicit adjustment bases #118
Description
Existing adjustment functions already implement latest-share-basis splits/dividends. Users migrating raw equity inputs also need validated event facts and imported source factors, without duplicating broker accounting or silently changing native adjustment definitions.
Public contract and ownership
Add adjustments.prepare_action_inputs and apply_adjustment_factors over native tables and existing kernels. Preserve source event/revision IDs, stable asset ID, announced/available/effective/ex/entitlement/payment dates, currency, ratio direction and share basis. Map existing physical names through feed_spec.
Data owns preparation/acquisition facts only. Supplied tables work independently of other libraries; shared types reuse Specs. No other owner's source changes are part of this issue.
Acceptance
- Retain raw values and expose price/volume factors. Existing apply_corporate_actions/apply_splits/apply_dividends defaults stay unchanged.
- A2:1 split with close200->98 and USD3 per post-split share gives gross shareholder return1.01; prior volume1000 rebases2000. Check intermediate factors, event-row invariance and same-date action composition.
- Zipline split price factor0.5 maps to native split_ratio2. Preserve supplied prior-close dividend factors with their convention rather than recomputing using native ex-date-close factors.
- Represent cash/stock distributions and merger facts without inventing missing destination IDs, consideration or availability. Validate only terms required for requested preparation; retain explicit coverage of unknown facts.
- Duplicate/conflicting revisions, invalid ratios, nonfinite amounts, ambiguous identity or incompatible units fail without caller/frame/store mutation.
- Public producer fixtures and offline guide produce accepted Backtest/Engineer input fields; Data does not alter orders, positions, entitlement or cash.
Run focused public API/regression tests first, then full final-revision native/source,ResourceWarning,coverage,type,docs,wheel/sdist,security and applicable hosted platform gates. Retain failing-base/passing-fix evidence for any bug; new capability tests use independent expected values. Include implementation,tests and executable migration docs in the same bounded PR. AI assistance must be disclosed and maintainer-reviewed.
Dependencies
Uses existing adjustment kernels and caller-supplied stable-ID table. Full dated registry is the following batch, not a blocker for validated captured tables.
Premises
Input: action-facts
| Question | Answer | Kind |
|---|---|---|
| record | One versioned source corporate-action fact, separate from a broker cash/position transition. | definitional |
| absent-record | Absence means missing source coverage,not automatically zero,no-trade,holiday or delisting. | definitional |
| ordering-spacing | Use declared timestamp/session semantics and grid/window unit; preserve observed keys rather than compressing gaps. | definitional |
| entity-identity | Stable asset identity is separate from source symbol,sid and display name; explicit mappings are required. | definitional |
| known-at | Source announced/available timestamps are retained; unknown availability is not copied from an ex-date. | definitional |
| institution | Source/exchange facts and selected authoritative schedule govern; this issue does not simulate trading. | definitional |
Claims
| Id | Claim | How it could be false |
|---|---|---|
| action-facts-workflow | The declared public producer and conversion workflow retains the contract and fails atomically on invalid input. | A real produced input loses keys,precision,source units,availability,missingness or revision identity; a reference-compatible route changes values/shapes/endpoints; or an error publishes partial output. |
Closes: action-facts.record, action-facts.absent-record, action-facts.ordering-spacing, action-facts.entity-identity, action-facts.known-at, action-facts.institution, action-facts-workflow
Advances: none
Plan reference: accepted Data successor implementation plan, Issue 2 in milestone Successor migration - Data inputs and provenance. Harmonized ownership: Data prepares inputs; Engineer owns features,Backtest execution,Diagnostic analytics. No publication/release authorization.
Activity
feat(adjustments): qualify captured action migration and preserve fac…
feat(history): prepare dated identities and known-at adjusted inputs (#…