Stale-Quote Detector: Tell a Quiet Market from a Broken Clock

Practical promise. Build a detector that can say which freshness dimension failed—without calling every unchanged quote an outage.

A price can sit still while messages and heartbeats continue normally. A quote can change yet arrive too late. A feed can stop delivering packets while the last displayed bid and ask still look plausible. Those states need different evidence and different operational responses.

This tutorial builds a causal detector for one instrument and feed. It separates four clocks:

1. source-event age at the current decision;
2. transport age of the latest quote;
3. local duration since bid or ask last changed; and
4. local duration since any quote or heartbeat arrived.

Only after those measurements exist does the detector apply an active-session business policy. That separation is the main lesson.

The five questions the output must answer

Suppose the screen still shows 100.00 / 100.02. “Is it stale?” hides five questions:

A heartbeat can keep liveness healthy while the quote remains unchanged. Conversely, the last quote may be recent but the absence of subsequent heartbeats can make the channel unusable. Neither condition proves what caused it.

Start with clock ownership

Each accepted event carries a receiver timestamp observed_ts. Quotes also carry a source timestamp source_event_ts.

The source and receiver clocks are different domains. Any subtraction across them assumes verified synchronization. That is why clock_sync_ok: true is a required quote field, not an optional annotation. FINRA Rule 6820 provides a concrete regulatory example of synchronization, drift checks, and documentation, although its CAT tolerances are not the thresholds used here.

Local durations are safer: the unchanged and heartbeat timers use only receiver-clock timestamps. In production, record a monotonic clock alongside wall-clock UTC so a time correction cannot make a duration run backward. The reference package rejects decreasing UTC observations and never silently clamps a negative age to zero.

The contract before the formula

The stream has three event types:

• quote updates bid/ask state and also proves feed activity;
• heartbeat proves feed activity without pretending the quote changed; and
• check evaluates elapsed time without pretending a packet arrived.

Every event includes a session_id, session_state, and activity_expected. A new session_id resets all state. INACTIVE and HALTED suppress the business classification, while raw measurements remain visible.

A quote is rejected before state mutation when:

• either timestamp is missing, invalid, or lacks a UTC offset;
• source/receiver synchronization is unverified;
• receive time precedes source time;
• source timestamps decrease within the session;
• bid or ask is missing, nonfinite, or nonpositive; or
• receiver timestamps decrease.

This detector does not decide whether a crossed quote is valid; that is a different invariant handled by the Crossed/Locked Market Detector.

Four clocks, one policy

At event $k$, define:

The four ages are:

$$s_k=c_k-e_q,\qquad \ell_q=r_q-e_q,\qquad u_k=c_k-r_\Delta,\qquad h_k=c_k-r_m.$$

$s_k$ and $\ell_q$ cross the source and receiver clocks. $u_k$ and $h_k$ stay inside the receiver domain.

Let $S$ be maximum source-event age, $L$ maximum transport age, $U$ the unchanged-duration threshold, and $H$ the heartbeat timeout. The reference equality rules are deliberately asymmetric:

$$s_k>S,\qquad \ell_q>L,\qquad u_k\ge U,\qquad h_k>H.$$

A maximum allowable age is still allowed at equality. A duration condition triggers when its boundary is reached. These choices are implementation policy, not universal market rules.

Business staleness is a separate gate:

$$\text{business-stale}_k= \text{active}_k\land\text{expected}_k\land (s_k>S\lor u_k\ge U).$$

Transport lateness and heartbeat loss remain separate operational reasons. The result may contain more than one reason.

Work the boundary by hand

Use $S=1200$ ms, $L=250$ ms, $U=3000$ ms, and $H=1200$ ms.

A quote with source time 09:30:00.000 arrives at 09:30:00.100. Its transport age is $100$ ms. At 09:30:01.200, its source-event age is exactly $1200$ ms, so the strict maximum-age rule has not fired.

A same-price quote later arrives at 09:30:02.500. It refreshes source-event age and heartbeat age, but it does not reset the unchanged anchor at 09:30:00.100. At 09:30:03.300, unchanged duration is $3200$ ms. The detector emits UNCHANGED_DURATION and, because the session is active and activity is expected, BUSINESS_STALE.

A changed pair received at 09:30:03.550 resets the unchanged duration. A later changed quote that takes $251$ ms to arrive emits TRANSPORT_AGE; price movement does not excuse late delivery.

The diagram's lower branch is important: a source timestamp later than its receive timestamp is rejected as clock skew or timestamp error. It is never labeled “fresh” and never allowed to reset state.

Update state only after validation

The order prevents a malformed quote from refreshing the heartbeat or resetting the unchanged timer. Both implementations expose a stateful detector so tests can prove that state survives a rejected event unchanged.

Heartbeats are not synthetic quote changes

Nasdaq's SoupBinTCP 4.0 protocol distinguishes sequenced data from logical heartbeats. Its server heartbeat schedule is protocol evidence, not permission to use one second as a universal application timeout.

The reference detector treats either a quote or heartbeat as feed activity. Only a quote can change the bid/ask pair. A check advances neither anchor. That makes these two situations observable:

• heartbeats continue while $u_k$ grows: the channel is alive, the value is unchanged;
• neither data nor heartbeats arrive while activity is expected: $h_k$ crosses its timeout.

Before any quote exists, quote-dependent ages are null, usability is false, and the reason is NO_QUOTE. Unknown is not fresh.

Calendar and session context change the meaning

At a regular-session close, a quote may remain unchanged for hours without constituting an active-market business failure. During a halt, the expected update pattern may differ again. The detector therefore accepts session context instead of embedding one exchange schedule.

source_event_age_exceeded may remain true outside the session; it is a raw measurement. business_stale becomes false when session_state is not ACTIVE or activity_expected is false. Heartbeat loss is also suppressed when activity is not expected.

The caller must provide a versioned exchange calendar, early closes, auctions, halts, and feed-specific service windows. This package cannot infer them from quote timestamps.

A real incident that shows why source identity matters

On August 22, 2013, UTP Vendor Alert 2013-9 records intermittent UQDF quote-channel outages at 11:48 ET and all outbound quote channels ceasing near 12:03. It reports that the technical issue was resolved and stable at 12:24, controlled connectivity return began at 14:00, and all Tape C quoting and trading resumed at 15:25. UTP trade feeds continued operating.

Nasdaq's separate trading post-mortem says proprietary market-data feeds were operating normally. The SEC's Regulation SCI release independently discusses the UTP SIP's inability to process quotes and the market-wide halt.

This is a documented quote-feed incident, not a generic flat-quote example. It teaches three precise lessons:

• source identity matters because quote, trade, consolidated, and proprietary paths can differ;
• technical repair time and the later coordinated market reopening are not the same interval; and
• an unchanged quote alone could not have established this cause.

No Financial Modeling Prep data case is used. End-of-day OHLCV cannot validate packet heartbeat or transport behavior.

Implementations and parity tests

The Python implementation and TypeScript implementation share the same 12-event JSON fixture. They emit the same numeric ages, flags, and ordered reason codes.

Tests cover:

• exact boundary values in both languages;
• heartbeats that refresh liveness without resetting quote value;
• active, inactive, halted, and new-session behavior;
• negative age and unverified clocks rejected before mutation;
• missing, naive, nonfinite, and out-of-order input; and
• no-quote and empty-stream state.

Those tests establish conformance to this definition. They do not establish threshold optimality, predictive power, or profitability.

Explore the four failure modes

Open the interactive stale-quote lab. Its initial normal state is already rendered. Then compare:

• Normal: quotes and heartbeats keep all clocks inside policy;
• Unchanged: heartbeats continue while the bid/ask pair crosses $U$;
• Heartbeat loss: checks continue after all feed packets stop;
• Clock skew: a negative transport age is rejected and prior state remains intact.

Use Back and Step to inspect one transition at a time. Reset always restores the same first accepted observation.

Failure modes that remain

• A low-activity instrument can cross an unchanged threshold while entirely valid.
• A heartbeat proves link activity, not economic quote freshness.
• This variant ignores size-only changes.
• Recent timestamps do not prove sequence completeness.
• Wall-clock synchronization does not replace a monotonic duration clock.
• One feed's condition says nothing about an independently sourced feed.
• usable_for_active_market is an engineering diagnostic, not an order-routing recommendation.

Keep raw observations, source identifiers, clock-sync logs, calendar versions, and reason codes. A single stale=true field is too lossy for incident analysis.

Summary and next topic

A useful stale-quote detector does not ask one vague question. It measures four clocks, rejects invalid clock comparisons, preserves independent reasons, and applies business policy only with explicit session context.

Continue with Duplicate-Trade Resolver, where identity and lifecycle state replace elapsed-time thresholds but the same validation-before-mutation discipline applies.