Learnings that shaped this package

Historical rationale, not additional API guarantees

These lessons came from the source study and subsequent library work. Study features such as portfolios and exchange-session timing remain outside this package. Current behavior is defined in Reference.

• Anchor every reading: A study join once reused one formation day’s signal across a holding window. Unit tests missed it; comparison with the original calculation on identical inputs exposed it. This motivates shared anchoring primitives and point-in-time checks.
• Preserve refusal reasons: Filtering stale rows before eligibility can turn a stale observation into an apparently missing one. Anchored publication retains ages for its checks; Bayesian freshness remains caller policy.
• Separate historical fitting from evaluation: Full-sample winsorisation once allowed test-period outliers to move training bounds. Each reading must derive statistics only from its allowed history. A frozen method object alone does not establish this guarantee.
• Record complete parameters: A version identifies a configuration but does not contain its values. Retain the payload, source snapshot and software revision; see the audit recipe.
• Validate at the boundary: A declared dataframe schema reports malformed inputs before arithmetic. A valid input can still be unpublishable; those cases carry a result row and reason rather than a substituted estimate.
• Test the port against its source: Worked examples and golden tests protect numerical behavior. Synthetic agreement establishes implementation parity, not predictive performance on real data.
• Keep provenance distinct from timestamps: The first actual in an export may already be revised. Historical model values may come from a later-selected model. The real-data walkthrough makes these limits explicit.