Repository navigation
Produce precise multi-horizon outcomes and Diagnostic handoff #110
Description
User workflow and ownership
Implement the accepted Engineer preparation/migration unit below. Preserve existing native defaults, dataframe contracts and independent use with supplied data. Data owns source adjustments/revision selection; Diagnostic owns the only Alphalens facade/cleaner and analytical workflows; Backtest owns simulation/accounting. Engineer produces native features, eligibility and outcomes, not competing engines.
Dependency: Issue 1 for common arithmetic. Endpoint and serialization tests are independent of
Issue 3. Extend labeling/horizon_labels.py, existing endpoint/grid utilities and owned label
definitions, adding a distinct multi-horizon route where required. Qualify native outputs through
Diagnostic's prepared-panel boundary; its owner supplies the sole Alphalens container adapter.
Accept explicit entry keys, horizon value/unit, method and feed/grid declarations. Preserve
observation, expected-bar, session-endpoint and elapsed-as-of definitions. Add cumulative versus
exit-bar-only returns, common-wide-grid versus per-asset indexing, endpoint tolerance, insufficient
tail handling and precise composite/subsecond targets. Reuse fixed-time labels' endpoint code
without changing their current defaults. Barrier exits remain separate. Each result retains entry,
requested exit, actual exit, outcome availability, method, unit and price basis. A duration-like
column name does not replace this metadata or imply that an overnight bar lasted one hour.
Native preparation never silently forward-fills prices. Diagnostic owns the explicit legacy
Alphalens research fill view and its trace. Engineer may consume such an explicitly declared view
for matched-method conformance, preserving original masks; it is not observed tradable input.
Expected-bar completeness validation is not disabled by that choice. No observed-gap holiday
inference replaces the canonical calendar contract. Full-sample z-score filtering and staged cleaning belong to the
receiving analytics library, not tradable Engineer features. A key-safe backshift handoff preserves
actual endpoints rather than blindly moving a sparse array.
Proposed focused files: tests/test_forward_return_endpoints.py and
tests/test_diagnostic_outcome_handoff.py. Verify with
uv run pytest tests/test_forward_return_endpoints.py tests/test_diagnostic_outcome_handoff.py -q.
Show 100/110/121 at horizon two gives cumulative .21 versus endpoint-only .1, with independently
checked keys. Test ragged assets, missing rows versus null quotes, timestamp mismatch, holiday/DST/
early close/overnight schedules, 30m/composite/1ms/1ns targets, named 24/7 versus row mode, and
omitted/metadata/override/None serialization. First reproduce fine-grained production failures
through public APIs before fixing; no precision truncation is an acceptable pass. Invalid or
incomplete declarations leave input and saved outputs untouched. Tail exclusions are explicit and
testable. Qualify equivalent external outcome tables so Engineer is never mandatory for analysis.
Premises
Input: outcome price grid
| Question | Answer | Kind |
|---|---|---|
| record | A supplied factor entry key and typed price observations define candidates for a declared future endpoint. | definitional |
| absent-record | Missing scheduled data fails completeness; absent tail/endpoints remain explicit exclusions, not zero returns or silent fills. | definitional |
| ordering-spacing | Horizon unit and endpoint method determine keys; common-grid and per-asset positions are distinct. | definitional |
| entity-identity | Stable asset and exact time keys identify entries/exits; sparse tables cannot be aligned by array position. | definitional |
| known-at | A realized label is available only after its selected prices are known and never qualifies as a contemporaneous feature. | definitional |
| institution | Existing FeedSpec resolver and actual schedule adapters govern market rules; explicit legacy missingness is a research method. | definitional |
Claims
| Id | Claim | How it could be false |
|---|---|---|
| endpoint-exactness | Outcomes preserve the declared entry/exit meaning and timestamp precision for every required horizon. | An asset shift skips a grid gap, a duration truncates, or a session label is treated as elapsed time. |
| outcome-compatibility | Supported native/adapted routes agree under the same endpoint, fill and arithmetic method. | The adapter changes cumulative meaning, forward-fills silently or loses sparse keys. |
| label-contract-roundtrip | Output persistence retains horizon/feed/basis/missingness declarations and actual endpoints. | Receiver must infer units/calendar from a label string or cannot recover an exit key. |
Closes: outcome-price-grid.record, outcome-price-grid.absent-record, outcome-price-grid.ordering-spacing, outcome-price-grid.entity-identity, outcome-price-grid.known-at, outcome-price-grid.institution, endpoint-exactness, outcome-compatibility, label-contract-roundtrip
Intake and completion
- Reproduce public producer defects before repairs and retain exact failing/passing revisions.
- Complete the methods, negative/error cases, runnable tests and migration route above.
- Verify actual installed outputs and the applicable final-revision quality/platform gates.
- Record producer/consumer dependencies separately from standalone qualification.
Plan reference: accepted Engineer preparation and Reloaded migration plan, unit 4 in milestone unreleased - Engineer preparation and Reloaded migration.
AI assistance: Codex prepared this intake projection from the accepted maintainer plan; implementation and independent test evidence are still required.
Activity
fix(labeling): retain nanosecond grids and elapsed windows
feat(labeling): produce keyed multi-horizon native outcomes
fix(labeling): reject overflowing outcomes and qualify input boundaries
feat(labeling): preserve research price-view observation masks
fix(labeling): retain decimal ticks and empty session endpoints
fix(labeling): make persisted fixed horizons directly replayable
chore: integrate merged precision prerequisite into outcome batch
feat(labeling): produce native keyed multi-horizon outcomes (#114)