# D01-F03-A05 — Asynchronous Return Alignment > **Status:** Video-ready | **Canonical variant:** event-time interval-overlap diagnostic ## Executive summary and learning contract A return is measured between two observations, so it owns an event-time interval rather than only an ending timestamp. This package determines whether two already-computed return intervals are exact, nested, partially overlapping, touching, or disjoint. It also records when the pair became jointly available. This is deliberately a **diagnostic, not a return estimator**. It does not split returns across shared time, multiply returns, estimate covariance, normalize an estimator, repair sampling bias, or produce a signal. After this topic, the reader can implement and audit interval geometry without confusing that prerequisite with a complete statistical method. ## Problem and financial relevance Two securities can update at different times. Pairing returns by end timestamp alone hides how much event time they actually share. The diagnostic answers: - Do the event intervals share positive duration? - What kind of interval relationship is present? - What fraction of each interval is shared? - When were both returns knowable at the same evaluation cutoff? Those facts can inform data-quality review or a downstream estimator. They do not determine how a downstream model should allocate returns or weight pairs. ## Prerequisites and scope Prerequisites are timestamp parsing, return construction, Exchange-Calendar Alignment, and Point-in-Time Availability Guard. Inputs are already-computed return intervals for exactly two instruments. The package excludes price-to- return construction, refresh-time sampling, lead-lag modeling, covariance and correlation estimation, inference, annualization, noise correction, and portfolio decisions. ## Input data contract | Field | Type | Meaning and rule | |---|---|---| | `return_id` | non-empty string | Unique identity after correction resolution | | `instrument` | non-empty string | Exactly one identity per input stream | | `partition` | non-empty string | Versioned session or analysis segment; pairs never cross it | | `event_start` | RFC 3339 UTC string | Exclusive beginning at whole-second or exactly millisecond precision | | `event_end` | RFC 3339 UTC string | Inclusive ending at the same supported precision; must be later than `event_start` | | `available_at` | RFC 3339 UTC string | First knowable instant at the same supported precision; cannot precede `event_end` | | `return_value` | optional finite number | Preserved for lineage but never used in geometry | Each stream must contain non-overlapping intervals within a partition. Touching adjacent intervals are allowed. Zero-length and reversed intervals are rejected. Currency, scale, price adjustment, return definition, venue, and calendar version belong to the upstream return product and must remain stable within a comparison. ### Corrections and versions The reference implementation accepts only an as-of, correction-resolved view. It rejects duplicate `return_id` values and overlapping intervals within one stream instead of guessing which revision wins. A production pipeline should retain raw versions, `available_at`, correction identifiers, and supersession times. When a correction arrives, recompute the affected partition under an explicit as-of cutoff. ## Time semantics Return $i$ owns the half-open event interval $$ I_i=(s_i,e_i]. $$ Its information state begins at $a_i=\texttt{available\_at}$. In an append-only view, the knowledge interval is $[a_i,\infty)$. If a correction supersedes the record at $c_i$, the version-specific knowledge interval is $[a_i,c_i)$; that end belongs to the upstream version store, not this diagnostic. For a pair $(i,j)$, the pair becomes knowable at $$ a_{ij}=\max(a_i,a_j). $$ At evaluation time $q$, the pair is jointly available exactly when $a_{ij}\le q$. Event overlap and availability are separate dimensions: two returns can overlap in event time but still be unavailable at a historical query cutoff. ## Event-overlap mathematics Let the two valid event intervals be $I_i=(s_i,e_i]$ and $J_j=(u_j,v_j]$. Their positive-duration overlap is $$ \omega_{ij}=\max\left(0,\min(e_i,v_j)-\max(s_i,u_j)\right). $$ The diagnostic reports two scale-free coverage fractions: $$ f^L_{ij}=\frac{\omega_{ij}}{e_i-s_i},\qquad f^R_{ij}=\frac{\omega_{ij}}{v_j-u_j}. $$ These fractions describe event-time coverage only. They are not return weights and must not be used to prorate returns without a separately justified model. ### Geometry classes | Class | Rule | Overlap duration | |---|---|---:| | `exact` | starts and ends are equal | positive | | `left_within_right` | left is fully contained in right | positive | | `right_within_left` | right is fully contained in left | positive | | `partial` | positive intersection without containment | positive | | `touching` | $\min(e_i,v_j)=\max(s_i,u_j)$ | zero | | `disjoint` | $\min(e_i,v_j)<\max(s_i,u_j)$ | zero | | `partition_mismatch` | partitions differ | not compared by the stream API | Invalid zero-length or reversed intervals are rejected rather than classified. ## Worked example Left interval $L=(0,4]$ seconds and right interval $R=(3,5]$ seconds overlap on $(3,4]$. Therefore $\omega=1$ second, $f^L=1/4$, and $f^R=1/2$. If the records became available at 4.2 and 5.25 seconds, the pair became jointly knowable at 5.25 seconds. At a 5.0-second historical cutoff, the event overlap exists but the pair is not yet available. Changing either return value does not change any of these diagnostics. ## Algorithm and output contract ```text validate identity, partition, timestamps, availability, uniqueness, and ordering reject unresolved corrections and overlapping intervals within either stream compare only pairs in the same partition calculate low = max(starts) and high = min(ends) classify disjoint, touching, exact, nested, or partial geometry report positive overlap duration and both coverage fractions report pair_available_at = max(source availability timestamps) evaluate point-in-time availability only when an evaluation cutoff is supplied aggregate diagnostic counts and event-time coverage; perform no return allocation ``` The output includes validated intervals, exhaustive same-partition pair diagnostics, positive-overlap pairs, class counts, total overlap milliseconds, side-specific coverage, and availability status. It also emits `diagnostic_only: true`, `estimator: null`, and `weighting_or_return_allocation: none` so downstream consumers cannot mistake the result for an estimator. ## What overlap can and cannot infer Overlap can establish shared event-time geometry and point-in-time knowability. It cannot show that price innovations occurred uniformly within either interval, identify which asset moved first, remove nonsynchronous-sampling bias, correct microstructure noise, establish covariance, imply causality, or predict returns. The Hayashi–Yoshida paper defines a complete covariance estimator that uses an overlap indicator to select return products under a stated stochastic model. That estimator is a downstream method; this package intentionally stops before the multiplication and sum. Likewise, the two coverage fractions here are diagnostics, not Hayashi–Yoshida weights. ## Testing and validation Python and TypeScript share `datasets/interval_cases.json`. Tests cover all six valid geometries, exact fractions, partition isolation, availability cutoffs, zero-length and reversed intervals, premature availability, duplicate IDs, intrastream overlap, and the invariance of geometry to return values. The fixture is synthetic CC0-1.0 and validates mechanics only. ## Historical-example decision A real market example is deferred. A credible case needs redistributable security-level observations with event timestamps, first-availability timestamps, correction state, identity mapping, and a documented session calendar. A public chart or end-of-day data file cannot establish those facts. Until that evidence exists, presenting named securities and dates would create false precision rather than a researched historical explanation. ## Visual explanations and related topics The [geometry SVG](visuals/static/return-overlaps.svg) compares partial, touching, and nested cases. The [interactive lab](visuals/animated/async-return-lab.html) steps through six geometry and availability scenarios. Previous-Tick Interpolation, Linear Quote Interpolation, Refresh-Time Sampling, and Exchange-Calendar Alignment are nearby synchronization methods; Point-in-Time Availability Guard supplies the as-of discipline used here. ## References See [REFERENCES.md](REFERENCES.md) for source roles and limitations.