Clarify lastSeenTimestampNs/lastUpdateTimestamp non-monotonicity on v8/v11 feeds

src/content/data-streams/reference/report-schema-v8.mdx

@@ -32,6 +32,19 @@ RWA streams adhere to the report schema outlined below.
   indicate when data was last recorded, not whether the market is currently active.
 </Aside>
 
+<Aside type="note" title="lastUpdateTimestamp is reliable but not guaranteed to be monotonic">
+  `lastUpdateTimestamp` remains the recommended field for assessing freshness, and reflects the median timestamp
+  across the data providers included in a given report. Because the result depends on exactly which providers are
+  included in a given report, a provider dropping in or out between reports can shift the median — and the fewer
+  providers contribute to a report, the more a single provider's inclusion or exclusion can move the result. For
+  example, if a provider is excluded from one report (due to a timeout) and included in the next, the median can
+  shift to an earlier value than the previous report. In the normal case, expect this value to advance with each
+  report. A single occurrence of non-monotonic movement is not by itself cause for concern — treat it as a potential
+  issue only if the behavior persists across multiple consecutive reports. Do not assume `lastUpdateTimestamp`
+  strictly increases from one report to the next. Improving the reliability of this behavior is an active area of
+  work. Use `marketStatus` to determine whether a market is open.
+</Aside>
+
 v8 streams use a three-value mapping:
 
 | Value | Status      | Description                        |

src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx

@@ -136,6 +136,17 @@ Consumers must treat `marketStatus = 5` (Closed) as a valid state and define det
 
 Markets may stop updating due to exchange outages, circuit breakers, trading halts, or corporate actions. The `marketStatus` field will continue reflecting the status that it normally would. Use the `lastSeenTimestampNs` field (which reflects the timestamp of the last update for the `mid` price only) to detect staleness by comparing it against the current time. When this timestamp stops advancing, it indicates the underlying venue has stopped providing updates.
 
+##### Why `lastSeenTimestampNs` can pause, or move non-monotonically, without an outage
+
+`mid` and its timestamp `lastSeenTimestampNs` are derived from a consensus across the data providers configured for a feed, and both only update when that consensus changes. Because the result depends on exactly which providers are included in a given report, any single provider dropping in or out can shift that result — and the fewer providers contribute to a report, the more a single provider's inclusion or exclusion can move the outcome. Two related behaviors follow from this:
+
+- **Pausing:** Individual data providers do not all publish at the same rate — some sourcing venues naturally have lower update frequency during certain windows, particularly for less liquid names or during thinner trading periods. When enough providers are momentarily quiet, the consensus value — and its timestamp — can hold steady for longer than you might expect, even though the DON is healthy and continuing to produce reports.
+- **Non-monotonic movement:** Which providers are actually included in a given report can also change from one report to the next, for example if a provider times out on one report and returns on the next. Because the timestamp is derived from whichever providers are included, it is not guaranteed to strictly increase — it can occasionally shift to an earlier value than the previous report's timestamp.
+
+In the normal case, expect `lastSeenTimestampNs` to advance in line with the update cadence for a given symbol and session. Neither of the above is a sign that the feed or DON is down. Do not assume `lastSeenTimestampNs` strictly increases between reports.
+
+A single stalled or backward-moving report is not, by itself, cause for concern. Treat it as a potential issue only if the behavior recurs across multiple consecutive reports, or the pause exceeds your own configured staleness threshold (see the staleness check example in [Stream Switching Example Logic](#stream-switching-example-logic)). At that point, apply your staleness safeguards regardless of whether the eventual cause turns out to be provider behavior or something else.
+
 Phase-specific feeds can introduce unique behavior due to venue-specific operational characteristics and market microstructure. The following are some examples of scenarios that may occur during session transitions or under specific market conditions:
 
 ##### Regular Hours Session: Delayed Quote Availability at Market Open