ic_query/ic/node_status/
model.rs

1//! Module: ic::node_status::model
2//!
3//! Responsibility: public observed node-status requests, evidence, reports, and errors.
4//! Does not own: source calls, cache IO, projection, or rendering.
5//! Boundary: preserves raw Dashboard status data and explicit off-chain/cache provenance.
6
7use crate::ic::IcDashboardReportProvenance;
8use serde::{Deserialize as SerdeDeserialize, Serialize};
9use std::fmt;
10#[cfg(feature = "dashboard-host")]
11use std::path::PathBuf;
12use thiserror::Error as ThisError;
13
14///
15/// IcNodeStatusScope
16///
17/// Dashboard collection scope retained by an observed node-status snapshot.
18///
19
20#[derive(Clone, Copy, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
21#[serde(rename_all = "snake_case")]
22pub enum IcNodeStatusScope {
23    /// Dashboard's default public-mainnet node set, excluding cloud-engine Type4 nodes.
24    DashboardMainnetDefault,
25}
26
27impl IcNodeStatusScope {
28    /// Return the stable serialized scope label.
29    #[must_use]
30    pub const fn as_str(self) -> &'static str {
31        match self {
32            Self::DashboardMainnetDefault => super::IC_NODE_STATUS_SCOPE,
33        }
34    }
35}
36
37///
38/// IcNodeOperationalStatus
39///
40/// Known Dashboard node-status classification used for filtering and counts.
41///
42
43#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize)]
44#[serde(rename_all = "snake_case")]
45pub enum IcNodeOperationalStatus {
46    /// The Dashboard reports the node as up.
47    Up,
48    /// The Dashboard reports the node as down.
49    Down,
50    /// The Dashboard reports the node as administratively disabled.
51    Disabled,
52    /// The Dashboard reports degraded operation.
53    Degraded,
54    /// The raw Dashboard value is not recognized by this release.
55    Unknown,
56}
57
58impl IcNodeOperationalStatus {
59    /// Classify raw Dashboard status text without discarding unknown future values.
60    #[must_use]
61    pub fn from_raw(raw: &str) -> Self {
62        match raw {
63            "UP" => Self::Up,
64            "DOWN" => Self::Down,
65            "DISABLED" => Self::Disabled,
66            "DEGRADED" => Self::Degraded,
67            _ => Self::Unknown,
68        }
69    }
70
71    /// Return the stable lowercase display label.
72    #[must_use]
73    pub const fn as_str(self) -> &'static str {
74        match self {
75            Self::Up => "up",
76            Self::Down => "down",
77            Self::Disabled => "disabled",
78            Self::Degraded => "degraded",
79            Self::Unknown => "unknown",
80        }
81    }
82}
83
84impl fmt::Display for IcNodeOperationalStatus {
85    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
86        formatter.write_str(self.as_str())
87    }
88}
89
90///
91/// IcNodeStatusCounts
92///
93/// Exact status totals derived from raw observed node rows.
94///
95
96#[derive(Clone, Debug, Default, Eq, PartialEq, SerdeDeserialize, Serialize)]
97pub struct IcNodeStatusCounts {
98    /// Total observed rows in the group.
99    pub total: usize,
100    /// Rows classified as `UP`.
101    pub up: usize,
102    /// Rows classified as `DOWN`.
103    pub down: usize,
104    /// Rows classified as `DISABLED`.
105    pub disabled: usize,
106    /// Rows classified as `DEGRADED`.
107    pub degraded: usize,
108    /// Rows whose raw status is not recognized.
109    pub unknown: usize,
110}
111
112impl IcNodeStatusCounts {
113    /// Return every row not classified as raw Dashboard `UP`.
114    #[must_use]
115    pub const fn non_up(&self) -> usize {
116        self.total.saturating_sub(self.up)
117    }
118}
119
120///
121/// IcNodeAssignmentStatusCounts
122///
123/// Operational-status totals partitioned by mutually exclusive assignment class.
124///
125
126#[derive(Clone, Debug, Default, Eq, PartialEq, SerdeDeserialize, Serialize)]
127pub struct IcNodeAssignmentStatusCounts {
128    /// Status totals for nodes with an observed assigned Subnet.
129    pub assigned: IcNodeStatusCounts,
130    /// Status totals for rows whose raw node type is `UNASSIGNED`.
131    pub unassigned: IcNodeStatusCounts,
132    /// Status totals for rows whose raw node type is `API_BOUNDARY`.
133    pub api_boundary: IcNodeStatusCounts,
134    /// Status totals for rows without a known assignment class.
135    pub unknown: IcNodeStatusCounts,
136}
137
138///
139/// IcNodeStatusGroupCounts
140///
141/// Overall and assignment-partitioned status totals for one aggregate group.
142///
143
144#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
145pub struct IcNodeStatusGroupCounts {
146    /// Raw operational-status totals for the group.
147    pub statuses: IcNodeStatusCounts,
148    /// Raw operational-status totals partitioned by assignment class.
149    pub assignment_statuses: IcNodeAssignmentStatusCounts,
150}
151
152///
153/// IcNodeCountComparison
154///
155/// Ordering of one observed node count relative to another.
156///
157
158#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
159#[serde(rename_all = "snake_case")]
160pub enum IcNodeCountComparison {
161    /// The left-hand count is smaller.
162    Less,
163    /// The two counts are equal.
164    Equal,
165    /// The left-hand count is larger.
166    Greater,
167}
168
169impl IcNodeCountComparison {
170    /// Compare a left-hand count with a right-hand count.
171    #[must_use]
172    pub const fn from_counts(left: usize, right: usize) -> Self {
173        if left < right {
174            Self::Less
175        } else if left > right {
176            Self::Greater
177        } else {
178            Self::Equal
179        }
180    }
181
182    /// Return the stable lowercase label.
183    #[must_use]
184    pub const fn as_str(self) -> &'static str {
185        match self {
186            Self::Less => "less",
187            Self::Equal => "equal",
188            Self::Greater => "greater",
189        }
190    }
191}
192
193///
194/// IcNodeCountComparisonCounts
195///
196/// Number of provider groups in each node-count comparison outcome.
197///
198
199#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
200pub struct IcNodeCountComparisonCounts {
201    /// Provider groups whose left-hand count is smaller.
202    pub less: usize,
203    /// Provider groups whose counts are equal.
204    pub equal: usize,
205    /// Provider groups whose left-hand count is larger.
206    pub greater: usize,
207}
208
209///
210/// IcNodeStatusRow
211///
212/// One raw node observation retained from the official Dashboard node resource.
213///
214
215#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
216pub struct IcNodeStatusRow {
217    /// Canonical node principal.
218    pub node_id: String,
219    /// Canonical node-operator principal.
220    pub node_operator_id: String,
221    /// Canonical node-provider principal.
222    pub node_provider_id: String,
223    /// Off-chain Dashboard node-provider name.
224    pub node_provider_name: String,
225    /// Raw Dashboard node type.
226    pub node_type: String,
227    /// Raw Registry reward type reported by the Dashboard.
228    pub node_reward_type: String,
229    /// Raw Dashboard operational status.
230    pub status: String,
231    /// Raw Dashboard alert name when present.
232    pub alert_name: Option<String>,
233    /// Assigned Subnet principal when present.
234    pub subnet_id: Option<String>,
235    /// CloudEngine Subnet principal when reported by the selected Dashboard scope.
236    pub cloud_engine_subnet_id: Option<String>,
237    /// Dashboard data-center identifier.
238    pub data_center_id: String,
239    /// Dashboard data-center name.
240    pub data_center_name: String,
241    /// Dashboard infrastructure owner label.
242    pub owner: String,
243    /// Raw Dashboard geographic region label.
244    pub region: String,
245    /// Observed GuestOS version when reported.
246    pub guestos_version: Option<String>,
247    /// Observed GuestOS trusted-execution status when reported.
248    pub guestos_tee_active: Option<bool>,
249    /// Observed node IP address when reported.
250    pub ip_address: Option<String>,
251    /// Observed IPv4-connectivity state when reported.
252    pub ipv4_connectivity_status: Option<bool>,
253    /// Dashboard hardware-generation label when reported.
254    pub node_hardware_generation: Option<String>,
255}
256
257impl IcNodeStatusRow {
258    /// Return the known classification of this row's raw status.
259    #[must_use]
260    pub fn operational_status(&self) -> IcNodeOperationalStatus {
261        IcNodeOperationalStatus::from_raw(&self.status)
262    }
263
264    /// Return whether the raw row is anything other than known `UP`.
265    #[must_use]
266    pub fn is_non_up(&self) -> bool {
267        self.operational_status() != IcNodeOperationalStatus::Up
268    }
269}
270
271///
272/// IcNodeStatusCacheEvidence
273///
274/// Caller-relative local cache evidence attached to a projected status report.
275///
276
277#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
278pub struct IcNodeStatusCacheEvidence {
279    /// Canonical local cache path used by the report.
280    pub cache_path: String,
281    /// Whether the cache is within the default age policy for this caller's time.
282    pub cache_fresh: bool,
283    /// Cache age at report construction.
284    pub age_seconds: u64,
285    /// Age threshold used to classify freshness.
286    pub stale_after_seconds: u64,
287}
288
289///
290/// IcNodeStatusObservation
291///
292/// Shared source, scope, and optional cache evidence for status reports.
293///
294
295#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
296pub struct IcNodeStatusObservation {
297    #[serde(flatten)]
298    /// Official Dashboard source provenance.
299    pub source: IcDashboardReportProvenance,
300    /// Explicit node collection scope.
301    pub scope: IcNodeStatusScope,
302    /// Whether cloud-engine nodes were included in the source collection.
303    pub cloud_engine_nodes_included: bool,
304    /// Local cache evidence, absent for a pure live snapshot.
305    pub cache: Option<IcNodeStatusCacheEvidence>,
306}
307
308///
309/// IcNodeStatusSnapshot
310///
311/// Complete canonical observed node snapshot used by every status projection.
312///
313
314#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
315pub struct IcNodeStatusSnapshot {
316    #[serde(flatten)]
317    /// Shared source and scope evidence.
318    pub observation: IcNodeStatusObservation,
319    /// Canonically ordered raw node rows.
320    pub nodes: Vec<IcNodeStatusRow>,
321}
322
323///
324/// IcNodeStatusSourceData
325///
326/// Untrusted raw node rows and provenance returned by a Dashboard source capability.
327///
328
329#[cfg(feature = "dashboard-host")]
330#[derive(Clone, Debug, Eq, PartialEq)]
331pub struct IcNodeStatusSourceData {
332    /// Source-call provenance echoed by the source.
333    pub source: crate::ic::IcSourceRequest,
334    /// Explicit Dashboard collection scope.
335    pub scope: IcNodeStatusScope,
336    /// Whether the source claims cloud-engine node inclusion.
337    pub cloud_engine_nodes_included: bool,
338    /// Raw observed node rows.
339    pub nodes: Vec<IcNodeStatusRow>,
340}
341
342///
343/// IcNodeStatusView
344///
345/// Target and attention selection shared by node, Subnet, and provider views.
346///
347
348#[derive(Clone, Debug, Default, Eq, PartialEq)]
349pub struct IcNodeStatusView {
350    /// Optional exact identifier or unique principal prefix.
351    pub target: Option<String>,
352    /// Whether fully-up rows or groups are included without a target.
353    pub include_all: bool,
354}
355
356impl IcNodeStatusView {
357    /// Construct the default attention-only view.
358    #[must_use]
359    pub const fn attention() -> Self {
360        Self {
361            target: None,
362            include_all: false,
363        }
364    }
365
366    /// Select one exact identifier or unique principal prefix.
367    #[must_use]
368    pub fn with_target(mut self, target: impl Into<String>) -> Self {
369        self.target = Some(target.into());
370        self
371    }
372
373    /// Include fully-up rows as well as attention rows.
374    #[must_use]
375    pub const fn with_all(mut self, include_all: bool) -> Self {
376        self.include_all = include_all;
377        self
378    }
379}
380
381///
382/// IcNodeStatusReport
383///
384/// Node-level view over one complete observed status snapshot.
385///
386
387#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
388pub struct IcNodeStatusReport {
389    #[serde(flatten)]
390    /// Shared source, scope, and cache evidence.
391    pub observation: IcNodeStatusObservation,
392    /// Total rows in the complete source snapshot.
393    pub snapshot_node_count: usize,
394    /// Snapshot-wide overall and assignment-partitioned totals.
395    pub counts: IcNodeStatusGroupCounts,
396    /// Whether the view includes fully-up rows.
397    pub include_all: bool,
398    /// Target text supplied by the caller.
399    pub requested_target: Option<String>,
400    /// Canonical target resolved by exact or unique-prefix matching.
401    pub resolved_target: Option<String>,
402    /// Stable label describing how the target resolved.
403    pub resolved_from: Option<String>,
404    /// Selected canonical node rows.
405    pub nodes: Vec<IcNodeStatusRow>,
406}
407
408///
409/// IcSubnetStatusRow
410///
411/// Observed operational counts and conservative threshold evidence for one Subnet.
412///
413
414#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
415pub struct IcSubnetStatusRow {
416    /// Canonical Subnet principal.
417    pub subnet_id: String,
418    /// Operational-status totals for observed assigned nodes.
419    pub statuses: IcNodeStatusCounts,
420    /// Byzantine fault count `floor((n - 1) / 3)` for the observed membership size.
421    pub fault_tolerance_node_count: usize,
422    /// Additional down nodes required for the down count to exceed the derived threshold.
423    pub additional_down_nodes_to_exceed_fault_tolerance: usize,
424    /// Additional non-up nodes required for the conservative count to exceed the threshold.
425    pub additional_non_up_nodes_to_exceed_fault_tolerance: usize,
426    /// Whether the observed down count already exceeds the derived threshold.
427    pub down_fault_tolerance_exceeded: bool,
428    /// Whether the observed conservative non-up count already exceeds the threshold.
429    pub conservative_non_up_fault_tolerance_exceeded: bool,
430    /// Raw non-up node evidence in canonical node order.
431    pub non_up_nodes: Vec<IcNodeStatusRow>,
432}
433
434///
435/// IcSubnetStatusReport
436///
437/// Subnet-level operational view over one complete observed node snapshot.
438///
439
440#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
441pub struct IcSubnetStatusReport {
442    #[serde(flatten)]
443    /// Shared source, scope, and cache evidence.
444    pub observation: IcNodeStatusObservation,
445    /// Total rows in the complete source snapshot.
446    pub snapshot_node_count: usize,
447    /// Snapshot rows with an assigned Subnet.
448    pub assigned_node_count: usize,
449    /// Number of observed Subnets before view filtering.
450    pub subnet_count: usize,
451    /// Number of observed Subnets containing a non-up node.
452    pub attention_subnet_count: usize,
453    /// Whether fully-up Subnets are included without a target.
454    pub include_all: bool,
455    /// Target text supplied by the caller.
456    pub requested_target: Option<String>,
457    /// Canonical Subnet target resolved by exact or unique-prefix matching.
458    pub resolved_target: Option<String>,
459    /// Stable label describing how the target resolved.
460    pub resolved_from: Option<String>,
461    /// Canonically ordered selected Subnet rows.
462    pub subnets: Vec<IcSubnetStatusRow>,
463}
464
465///
466/// IcNodeProviderStatusRow
467///
468/// Assignment and raw operational counts for one observed node provider.
469///
470
471#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
472pub struct IcNodeProviderStatusRow {
473    /// Canonical node-provider principal.
474    pub node_provider_id: String,
475    /// Off-chain Dashboard provider name.
476    pub node_provider_name: String,
477    /// Operational-status and assignment totals for the provider.
478    pub counts: IcNodeStatusGroupCounts,
479    /// Unassigned up-node count compared with assigned up-node count.
480    pub unassigned_up_vs_assigned_up: IcNodeCountComparison,
481    /// Unassigned non-up-node count compared with assigned non-up-node count.
482    pub unassigned_non_up_vs_assigned_non_up: IcNodeCountComparison,
483    /// Raw non-up node evidence in canonical node order.
484    pub non_up_nodes: Vec<IcNodeStatusRow>,
485}
486
487///
488/// IcNodeProviderStatusReport
489///
490/// Node-provider operational view over one complete observed node snapshot.
491///
492
493#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
494pub struct IcNodeProviderStatusReport {
495    #[serde(flatten)]
496    /// Shared source, scope, and cache evidence.
497    pub observation: IcNodeStatusObservation,
498    /// Total rows in the complete source snapshot.
499    pub snapshot_node_count: usize,
500    /// Number of observed provider principals before view filtering.
501    pub provider_count: usize,
502    /// Number of provider groups containing a non-up node.
503    pub attention_provider_count: usize,
504    /// All-provider outcomes for unassigned up nodes compared with assigned up nodes.
505    pub unassigned_up_vs_assigned_up_provider_counts: IcNodeCountComparisonCounts,
506    /// All-provider outcomes for unassigned non-up nodes compared with assigned non-up nodes.
507    pub unassigned_non_up_vs_assigned_non_up_provider_counts: IcNodeCountComparisonCounts,
508    /// Whether fully-up providers are included without a target.
509    pub include_all: bool,
510    /// Target text supplied by the caller.
511    pub requested_target: Option<String>,
512    /// Canonical provider target resolved by exact or unique-prefix matching.
513    pub resolved_target: Option<String>,
514    /// Stable label describing how the target resolved.
515    pub resolved_from: Option<String>,
516    /// Canonically ordered selected provider rows.
517    pub providers: Vec<IcNodeProviderStatusRow>,
518}
519
520///
521/// IcNodeStatusProjectionError
522///
523/// Failure to resolve or project a requested observed status view.
524///
525
526#[derive(Clone, Debug, Eq, PartialEq, ThisError)]
527pub enum IcNodeStatusProjectionError {
528    /// Observation provenance, raw rows, canonical ordering, or counts are invalid.
529    #[error("invalid observed node-status snapshot: {reason}")]
530    InvalidSnapshot {
531        /// Deterministic validation failure.
532        reason: String,
533    },
534    /// The supplied target is empty after trimming.
535    #[error("{kind} target must not be empty")]
536    EmptyTarget {
537        /// Projection kind being selected.
538        kind: &'static str,
539    },
540    /// No observed identifier matches the supplied target.
541    #[error("{kind} target {target:?} did not match the observed snapshot")]
542    UnknownTarget {
543        /// Projection kind being selected.
544        kind: &'static str,
545        /// Unmatched target text.
546        target: String,
547    },
548    /// More than one observed identifier matches the supplied prefix.
549    #[error("{kind} prefix {prefix:?} is ambiguous; matches: {matches:?}")]
550    AmbiguousTarget {
551        /// Projection kind being selected.
552        kind: &'static str,
553        /// Ambiguous principal prefix.
554        prefix: String,
555        /// Canonically ordered matching principals.
556        matches: Vec<String>,
557    },
558}
559
560///
561/// IcNodeStatusCacheRequest
562///
563/// Stable identity of one network-level observed node-status cache.
564///
565
566#[cfg(feature = "dashboard-host")]
567#[derive(Clone, Debug, Eq, PartialEq)]
568pub struct IcNodeStatusCacheRequest {
569    /// Root directory containing all `ic-query` caches.
570    pub cache_root: PathBuf,
571    /// Requested network name.
572    pub network: String,
573}
574
575#[cfg(feature = "dashboard-host")]
576impl IcNodeStatusCacheRequest {
577    /// Construct one observed node-status cache identity.
578    #[must_use]
579    pub fn new(cache_root: impl Into<PathBuf>, network: impl Into<String>) -> Self {
580        Self {
581            cache_root: cache_root.into(),
582            network: network.into(),
583        }
584    }
585}
586
587///
588/// IcNodeStatusRefreshRequest
589///
590/// Settings for one forced observed node-status snapshot refresh.
591///
592
593#[cfg(feature = "dashboard-host")]
594#[derive(Clone, Debug, Eq, PartialEq)]
595pub struct IcNodeStatusRefreshRequest {
596    /// Stable cache identity.
597    pub cache: IcNodeStatusCacheRequest,
598    /// Explicit Dashboard API base endpoint.
599    pub source_endpoint: String,
600    /// Caller-supplied observation time as Unix seconds.
601    pub now_unix_secs: u64,
602}
603
604#[cfg(feature = "dashboard-host")]
605impl IcNodeStatusRefreshRequest {
606    /// Construct one forced node-status snapshot refresh request.
607    #[must_use]
608    pub fn new(
609        cache_root: impl Into<PathBuf>,
610        network: impl Into<String>,
611        source_endpoint: impl Into<String>,
612        now_unix_secs: u64,
613    ) -> Self {
614        Self {
615            cache: IcNodeStatusCacheRequest::new(cache_root, network),
616            source_endpoint: source_endpoint.into(),
617            now_unix_secs,
618        }
619    }
620}
621
622///
623/// IcNodeStatusReadRequest
624///
625/// Cache-backed status-view request shared by node, Subnet, and provider reports.
626///
627
628#[cfg(feature = "dashboard-host")]
629#[derive(Clone, Debug, Eq, PartialEq)]
630pub struct IcNodeStatusReadRequest {
631    /// Live and cache settings used when refresh is required.
632    pub refresh: IcNodeStatusRefreshRequest,
633    /// Projection target and attention selection.
634    pub view: IcNodeStatusView,
635    /// Whether to force a live replacement before reading.
636    pub force_refresh: bool,
637}
638
639#[cfg(feature = "dashboard-host")]
640impl IcNodeStatusReadRequest {
641    /// Construct one stale-refresh status-view request.
642    #[must_use]
643    pub fn new(
644        cache_root: impl Into<PathBuf>,
645        network: impl Into<String>,
646        source_endpoint: impl Into<String>,
647        now_unix_secs: u64,
648    ) -> Self {
649        Self {
650            refresh: IcNodeStatusRefreshRequest::new(
651                cache_root,
652                network,
653                source_endpoint,
654                now_unix_secs,
655            ),
656            view: IcNodeStatusView::attention(),
657            force_refresh: false,
658        }
659    }
660}
661
662///
663/// IcNodeStatusRefreshReport
664///
665/// Result of atomically replacing the complete observed node-status cache.
666///
667
668#[cfg(feature = "dashboard-host")]
669#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
670pub struct IcNodeStatusRefreshReport {
671    /// Cache/report schema version.
672    pub schema_version: u32,
673    /// Network identity attached to the replacement.
674    pub network: String,
675    /// Explicit Dashboard endpoint queried.
676    pub source_endpoint: String,
677    /// Canonical UTC collection timestamp.
678    pub fetched_at: String,
679    /// Collector identity.
680    pub fetched_by: String,
681    /// Published cache path.
682    pub cache_path: String,
683    /// Sibling refresh-lock path.
684    pub refresh_lock_path: String,
685    /// Whether an existing complete snapshot was replaced.
686    pub replaced_existing_cache: bool,
687    /// Number of published node rows.
688    pub node_count: usize,
689    /// Published overall and assignment-partitioned status totals.
690    pub counts: IcNodeStatusGroupCounts,
691}
692
693///
694/// IcNodeStatusHostError
695///
696/// Host source, cache, and projection failures for observed node-status reports.
697///
698
699#[cfg(feature = "dashboard-host")]
700#[derive(Debug, ThisError)]
701pub enum IcNodeStatusHostError {
702    /// The observed Dashboard source supports only public mainnet identity.
703    #[error("observed IC node status supports only the mainnet `ic` network, not {network:?}")]
704    UnsupportedNetwork {
705        /// Unsupported requested network.
706        network: String,
707    },
708    /// Live-source or source-validation failure.
709    #[error(transparent)]
710    Source(#[from] crate::ic::IcHostError),
711    /// Pure projection failure.
712    #[error(transparent)]
713    Projection(#[from] IcNodeStatusProjectionError),
714    /// Strict cache load found no complete snapshot.
715    #[error("observed node-status cache is missing at {}", path.display())]
716    MissingCache {
717        /// Expected cache path.
718        path: PathBuf,
719    },
720    /// Existing cache snapshot-key identity does not match its path.
721    #[error(
722        "observed node-status cache identity mismatch at {}: {field} is {actual:?}, expected {expected:?}",
723        path.display()
724    )]
725    CacheIdentityMismatch {
726        /// Cache path that failed validation.
727        path: PathBuf,
728        /// Identity field that differs.
729        field: &'static str,
730        /// Required identity value.
731        expected: String,
732        /// Stored identity value.
733        actual: String,
734    },
735    /// Existing cache is structurally readable but semantically invalid.
736    #[error("invalid observed node-status cache at {}: {reason}", path.display())]
737    InvalidCache {
738        /// Cache path that failed validation.
739        path: PathBuf,
740        /// Deterministic validation failure.
741        reason: String,
742    },
743    /// Shared generic JSON, filesystem, or refresh-lock cache failure.
744    #[error(transparent)]
745    Cache(#[from] crate::cache_file::HostCacheError),
746}
ic_query/ic/node_status/model.rs

ic_query/ic/node_status/
model.rs
