docs(chart,tuner): correct docstrings after all-cores and axis-keep

crates/moon-ui-gpui/src/analytics/mod.rs

@@ -1147,19 +1147,19 @@ impl AnalyticsView {
     /// The "By filter" joint suggestion is the one exception. It runs through `spawn_db`, which
     /// installs no read-cancellation token, so it is not among the lanes `cancel_latest_reads`
     /// retires — no interrupt can reach it, and therefore no fake `Settled` can be published for
-    /// it. A live joint run finishes on the axis it started on, and its result is captioned as
-    /// fitted across the move. A minutes-long composition is the most expensive thing this window
-    /// does, and a report generation advance — a strictly larger change — already does not retire
-    /// it (`TunerState::mark_report_stale`). `TunerState::invalidate_for_axis` is that path. With
-    /// no joint run live the tuner is invalidated exactly as before: drafts cleared, every
-    /// identity retired.
+    /// it. Once that run has materialized its sample, an adoption does not rescan it; the result
+    /// is captioned as fitted across the move. A minutes-long composition is the most expensive
+    /// thing this window does, and a report generation advance — a strictly larger change —
+    /// already does not retire it (`TunerState::mark_report_stale`).
+    /// `TunerState::invalidate_for_axis` is that path. With no joint run live the tuner is
+    /// invalidated exactly as before: drafts cleared, every identity retired.
     ///
     /// Args:
     ///     cx: Analytics window context used to schedule a catch-up only when the axis moved.
     ///
     /// Returns:
-    ///     Nothing; an axis change retires every in-flight read identity and schedules a
-    ///     writer-driven catch-up.
+    ///     Nothing; an axis change retires in-flight read identities other than a live joint
+    ///     suggestion, and schedules a writer-driven catch-up.
     fn observe_report_axis(&mut self, cx: &mut Context<Self>) {
         let axis = self.backend.read(cx).report_axis(self.display_zone);
         if axis == self.axis {

crates/moon-ui-gpui/src/analytics/tuner/filter/state.rs

@@ -637,8 +637,10 @@ impl TunerState {
     /// a committed report row — a strictly larger change — must not retire a manually started
     /// search.
     ///
-    /// Only [`SuggestJob::AllFields`] and [`SuggestJob::Compose`] can carry the mark. Idle, a
-    /// finished result, a failure and a single-field sweep are left unchanged.
+    /// Only a live [`SuggestJob::AllFields`] or [`SuggestJob::Compose`] is marked here. Idle, a
+    /// failure and a single-field sweep are left unchanged. A finished [`SuggestState::Done`]
+    /// already carries the copy taken when the job was replaced, and this function does not
+    /// write it again.
     ///
     /// Returns:
     ///     Whether a live joint run was there to mark.

crates/moon-ui-gpui/src/analytics/tuner/shell.rs

@@ -388,7 +388,9 @@ impl AnalyticsView {
     ///
     /// Head facts are `flex_none` children of this band; the tail is one `overflow_hidden` box.
     /// LTR clipping is the priority order. The tooltip is built from the same facts, so a clipped
-    /// tail stays recoverable.
+    /// tail stays recoverable. A finished joint run that was live across a report-axis adoption
+    /// appends that note and takes the warning tone. A running search does not: its progress
+    /// caption already owns the band.
     ///
     /// Args:
     ///     p: Active MoonUI palette.

crates/moon-ui-gpui/src/chartdx/data_state/orders.rs

@@ -124,9 +124,9 @@ impl ChartDataState {
                 pr.core_name = core_name;
                 pixels_changed = true;
             }
-            // Same foreign-admission test as `pane_admits_record`: this pane owns the history
-            // request and the admitted set holds more than the owner. A compare pane that does
-            // not own the request keeps its own name.
+            // Owner pane of a widened set: the same `owner == pane` gate `pane_admits_record`
+            // uses before a foreign trade may draw, and the set holds more than the owner. A
+            // compare pane that does not own the request keeps its own name.
             let all_cores_count = self.trade_history_cores.as_ref().and_then(|cores| {
                 (cores.owner == pane.core && cores.admitted.len() > 1)
                     .then_some(cores.admitted.len())

crates/moon-ui-gpui/src/chartdx/mod.rs

@@ -414,11 +414,12 @@ struct PaneRender {
     market: String,
     /// Core name for the chart corner label, resolved from `SessionManager` during order sync.
     core_name: String,
-    /// Admitted-core count for that same caption, or `None` when the pane draws only its own core.
+    /// Admitted-core count for that same caption, or `None` when this pane does not name a
+    /// widened set.
     ///
-    /// `Some(n)` means this pane owns the history request and `n` cores were admitted — the same
-    /// test `pane_admits_record` uses before it will draw a foreign trade. The caption string is
-    /// built from this in `refresh_pane_labels`, not here.
+    /// `Some(n)` means this pane owns the history request and `n` cores were admitted. A foreign
+    /// trade draws only on that owner pane (`pane_admits_record`); a follower keeps `None` and its
+    /// own name. The caption string is built from this in `refresh_pane_labels`, not here.
     all_cores_count: Option<usize>,
     /// Ticker for that same caption (`BEAT-USDT`), resolved from the core's catalog in
     /// `sync_from_market_source` and cached here.
@@ -1602,8 +1603,9 @@ struct ChartDataState {
     trade_history: std::rc::Rc<Vec<moon_core::db::ChartTradeRecord>>,
     /// Cores the panel admitted for `trade_history`, or `None` when no set was handed over.
     ///
-    /// `None` is every panel that was never handed a set — every panel today, and the frozen
-    /// Trade window always — and `None` means own-core only.
+    /// `None` draws own-core only: no history load has published a set, the target was cleared, or
+    /// this is the frozen Trade window, which publishes records and never hands a set over. A chart
+    /// load stores `Some` even when the flag is off and the set is only the owner.
     trade_history_cores: Option<std::rc::Rc<trade_history_sync::TradeHistoryCores>>,
     /// The time axis this engine's replicated closed-trade stamps are corrected on.
     ///

crates/moon-ui-gpui/src/chartdx/trade_history_sync.rs

@@ -59,17 +59,16 @@ pub(super) fn trade_kind_visible(
 
 /// Whether one closed-trade record may draw on this pane.
 ///
-/// A panel's `trade_history` is ONE list loaded for ONE `(core, market)` target, and a multi-pane
-/// panel (the Compare kind) draws that same list on every pane. Only the pane whose core OWNS the
-/// request may widen to the admitted set; every other pane keeps today's own-core rule, or a
-/// Compare pane would draw the anchor pane's foreign trades. That is why `owner == pane` is
-/// load-bearing.
+/// A panel's `trade_history` is one list for one `(core, market)` request, and a multi-pane panel
+/// (the Compare kind) draws that same list on every pane. A record whose core is this pane's core
+/// draws. A foreign record draws only when this pane owns the request (`owner == pane`) and the
+/// record's core is in `admitted`; otherwise a Compare follower would draw the anchor pane's
+/// foreign trades.
 ///
-/// Once the panel is handed a widened set, a non-owner Compare pane begins drawing ITS OWN core's
-/// rows out of that shared list, where today it draws nothing — today the list holds only the
-/// owner's rows. That is deliberate and strictly flag-gated: with the toggle off the admitted set
-/// is just the owner, so a follower pane draws nothing exactly as it does now. `owner == pane`
-/// still stops a follower from drawing OTHER cores' trades.
+/// With the flag off the admitted set is only the owner, so the list holds only that core's rows
+/// and a follower pane draws nothing. With the flag on the list holds every admitted core, and a
+/// follower draws its own core's rows from it. `owner == pane` still stops that follower from
+/// drawing any other core.
 ///
 /// `None` is own-core only. That is a panel which has not loaded a target yet, and the frozen
 /// Trade window, which publishes records but never hands over a core set. A loaded panel stores

crates/moon-ui-gpui/src/panels/chart/report_trades.rs

@@ -419,6 +419,10 @@ impl ChartPanel {
 
     /// Start one exact-target durable read, optionally replacing visible state and refocusing.
     ///
+    /// The admitted core set is stored on the chart before any early return. Turning the flag off
+    /// therefore drops foreign arrows immediately, and turning it on widens the draw filter while
+    /// the rows still on screen belong to the previous core.
+    ///
     /// Args:
     ///     core: Exact runtime core captured by the producer.
     ///     market: Catalog-verified canonical market.
@@ -677,6 +681,10 @@ impl ChartPanel {
 
     /// Whether a history request for this target would repeat work already done or under way.
     ///
+    /// `cores` is the admitted set, the chart's own core first. It is compared with the set
+    /// already stored, in that order, so a wider or narrower admission is not the same request.
+    /// Alias spelling is a separate wake ([`Self::requery_trade_history_on_core_scope`]).
+    ///
     /// `Loading | Ready | Empty` are settled: the answer is either in hand or on its way. The two
     /// FAILURE states are not settled — they must be retried — but not on demand: an unavailable
     /// replica would otherwise turn a busy detect feed, which re-adds the same market to extend its