Data contracts

Series

A scalar, time-indexed value with provenance. Used for predictors, targets, returns, prices, factors, and forecast series.

Panel

A date-by-entity matrix. Used for cross-sectional sorting and factor construction. Returns panels must declare survivorship treatment.

EventCalendar

Sorted, deduplicated event timestamps known at the relevant decision time. Used for event studies.

EventMarketPanel

Per-event market structures with prices and outcomes. Settlement information must not leak into entry features.

Unavailable

An explicit refusal when a contract cannot be met. Penrose does not fabricate a substitute merely because a claim expects a series.

Cleaned-data vintage & the sentry loader

Vendor bad prints, such as zero or near-zero futures prices, are repaired before serving as a versioned, content-addressed derived cleaned artifact. The raw bytes remain preserved and hashed; the cleaned bytes are separately hashed; and a repair manifest records the deterministic transform. Repairs must be causal and may not use future observations.

The serve-time loader is a non-mutating sentry: it flags residual anomalies and returns Unavailable when the contract cannot be met, but never silently repairs or fabricates a fallback. Cleaning creates a new derived vintage. A loader that silently repairs is a loader that disagrees with its own hash, because artifact_sha256 must describe the bytes actually served.

Shared requirements

• provenance;
• deterministic ordering;
• declared frequency;
• no look-ahead;
• venue compatibility;
• point-in-time semantics;
• graceful handling of missing and degenerate data.