Reversion Safety tools for overseer and subsystems (#3104)

* guide: reversion safety

* guide: manage reversion safety in subsystems

* add leaf status to ActivatedLeaf

* add an LRU-cache to overseer for staleness detection

* update ActivatedLeaf usages in tests to contain status field

* add variant where missed accidentally

* add some helpers to LeafStatus

* address grumbles

polkadot/node/subsystem/src/lib.rs

@@ -46,6 +46,36 @@ use self::messages::AllMessages;
 /// If there are greater than this number of slots, then we fall back to a heap vector.
 const ACTIVE_LEAVES_SMALLVEC_CAPACITY: usize = 8;
 
+
+/// The status of an activated leaf.
+#[derive(Debug, Clone)]
+pub enum LeafStatus {
+	/// A leaf is fresh when it's the first time the leaf has been encountered.
+	/// Most leaves should be fresh.
+	Fresh,
+	/// A leaf is stale when it's encountered for a subsequent time. This will happen
+	/// when the chain is reverted or the fork-choice rule abandons some chain.
+	Stale,
+}
+
+impl LeafStatus {
+	/// Returns a bool indicating fresh status.
+	pub fn is_fresh(&self) -> bool {
+		match *self {
+			LeafStatus::Fresh => true,
+			LeafStatus::Stale => false,
+		}
+	}
+
+	/// Returns a bool indicating stale status.
+	pub fn is_stale(&self) -> bool {
+		match *self {
+			LeafStatus::Fresh => false,
+			LeafStatus::Stale => true,
+		}
+	}
+}
+
 /// Activated leaf.
 #[derive(Debug, Clone)]
 pub struct ActivatedLeaf {
@@ -53,6 +83,8 @@ pub struct ActivatedLeaf {
 	pub hash: Hash,
 	/// The block number.
 	pub number: BlockNumber,
+	/// The status of the leaf.
+	pub status: LeafStatus,
 	/// An associated [`jaeger::Span`].
 	///
 	/// NOTE: Each span should only be kept active as long as the leaf is considered active and should be dropped