feat(adjustments): prepare versioned action facts and explicit factors - #126

Workflow

Prepare versioned corporate-action facts and imported price/volume factors without changing native financial definitions or adding broker accounting.

Closes #118. Prerequisites #123 and #125 are merged. This PR targets main and incorporates it through a normal merge preserving both histories.

Implementation

• prepare_action_inputs retains stable IDs, event/revision/source identity, raw terms and announced/available/effective/ex/entitlement/payment dates. Imported split conventions are explicit; rational terms must agree. Captured instrument membership validates source and destination IDs. Unknown applicable terms remain null with coverage, not invented consideration.
• apply_adjustment_factors preserves raw observations and supplied definitions. Exact unique key coverage, positive finite factors, currency compatibility and reserved output fields are validated before output. Volume adjusts only when supplied. No orders, positions, entitlement or payment effects.
• Shared FeedSpec mappings and omission/null calendar declarations are reused. Existing API/migration pages include a runnable CSV-to-facts-to-disk native/vendor example. Existing adjustment kernel defaults remain unchanged.

Executed qualification

• The earlier complete runtime source passed 4,289 tests separately in native and ResourceWarning-error lanes, with coverage, lint, format, ty, strict docs, wheel/sdist, actionlint and hooks. Final review then reproduced one additional validation defect; that historical result does not qualify the repair by itself. All final-head hosted full-suite gates remain required.
• Independent oracle: raw prices 200 to 98, split ratio 2 and USD3 per post-event share produce native factor 98/202, shareholder return 1.01 and prior adjusted volume 2000 from raw1000. Imported vendor factor .485 stays distinct and gives prior adjusted close97. A public regression reproduces and prevents source-method provenance overwrite on factor-table reimport.
• Final reviewed head 79dd1e9f78b577027807824dbc1b9aa49e49dd3f additionally rejects overflow/underflow after split-ratio normalization. Three actual CSV-input regressions fail on 5a4b2ba and pass with the repair; 134 focused adjustment/handoff ResourceWarning tests, lint, format, ty and hooks pass. All seven premise/claim correct/failing-producer controls pass again on the repaired source, without waivers or deferrals.
• Fresh wheel and sdist identify Data 0.2.2.dev28+g79dd1e9f7; all167 packaged source files match that Git revision. Both isolated installs also reject the three invalid derived-ratio cases through the actual public API.
• Both freshly installed artifacts run the actual offline recipe through public Engineer and Diagnostic APIs. Native return .01 and preserved vendor return 1/97 pass; raw prices200/98 and volumes1000/7 remain unchanged. Qualification used Specs0.2.0, Engineer immutable source c69e7badaac012ad98b1c4b8aa9a67a952b08f5c, Diagnostic0.1.9, pandas3.0.6 and Polars2.0.0. This is source-candidate integration, not a claim that the currently released Engineer resolves with Specs0.2.
• All27 final-head checks are completed:26success and the sole configured Python3.15 prerelease skip,with its exception-validation check successful. Both nine-platform supported and ecosystem lanes,coverage,security,strict docs and packaging checks pass on79dd. Superseded stacked/draft cancellations or exclusions are not counted as passes.

No causal as-of guarantee is claimed by this preparation API. No analytical cleaner, runtime history engine, broker, mandatory Reloaded dependency, release, tag, publication or documentation deployment.

AI assistance was used for implementation, tests and documentation. The producing workflow, substantive diff, independent financial oracles and failure controls were reviewed in the Data owner workflow.