Skip to main content

spacedb_console/
observe.rs

1//! What the console observes — the raw state an operator's adapters feed in.
2//!
3//! These are deliberately plain DTOs, not the live types of each SpaceDB layer:
4//! the console is a *read-model*, fed by an adapter that translates fleet /
5//! access / meter state into observations. That keeps it decoupled and lets the
6//! whole dashboard be computed (and tested) from a snapshot.
7
8use serde::{Deserialize, Serialize};
9use spacedb_meter::Resource;
10
11/// A home computer in the fleet.
12#[derive(Clone, Debug, Serialize, Deserialize)]
13pub struct HomeObs {
14    pub id: String,
15    pub region: String,
16    pub online: bool,
17}
18
19/// A stored shard and its replication standing.
20#[derive(Clone, Debug, Serialize, Deserialize)]
21pub struct ShardObs {
22    pub id: String,
23    pub collection: String,
24    /// Replicas currently reachable.
25    pub reachable_replicas: u32,
26    /// The replication target.
27    pub target_replicas: u32,
28    /// Minimum copies needed to not lose the data (1 for replication, k for k-of-n
29    /// erasure coding).
30    pub durable_floor: u32,
31    pub size_bytes: u64,
32}
33
34impl ShardObs {
35    /// Below the data already cannot be reconstructed.
36    pub fn lost(&self) -> bool {
37        self.reachable_replicas < self.durable_floor
38    }
39
40    /// Exactly at the floor — a single further loss means data loss.
41    pub fn at_risk(&self) -> bool {
42        self.reachable_replicas == self.durable_floor
43    }
44
45    /// Below the desired redundancy (but maybe still safe).
46    pub fn under_replicated(&self) -> bool {
47        self.reachable_replicas < self.target_replicas
48    }
49
50    /// Above the target — surplus copies that are reclaimable cost, not danger
51    /// (e.g. a repaired-away shard whose original home rejoined).
52    pub fn over_replicated(&self) -> bool {
53        self.reachable_replicas > self.target_replicas
54    }
55
56    /// How many replicas above target.
57    pub fn excess(&self) -> u32 {
58        self.reachable_replicas.saturating_sub(self.target_replicas)
59    }
60}
61
62/// A strong-tier collection's quorum standing.
63#[derive(Clone, Debug, Serialize, Deserialize)]
64pub struct StrongObs {
65    pub collection: String,
66    pub members_online: u32,
67    pub members_total: u32,
68}
69
70impl StrongObs {
71    /// Whether a majority is reachable — i.e. it can still serve linearizable ops.
72    pub fn has_quorum(&self) -> bool {
73        self.members_online > self.members_total / 2
74    }
75}
76
77/// A collection's convergence lag on some replica.
78#[derive(Clone, Debug, Serialize, Deserialize)]
79pub struct LagObs {
80    pub collection: String,
81    pub lag_ops: u64,
82    pub region: Option<String>,
83}
84
85/// An issued capability (human or AI agent).
86#[derive(Clone, Debug, Serialize, Deserialize)]
87pub struct CapabilityObs {
88    pub bearer: String,
89    pub scope: String,
90    pub ops: String,
91    pub expiry: Option<u64>,
92    pub budget_micro_mata: Option<u64>,
93    pub revoked: bool,
94}
95
96impl CapabilityObs {
97    /// An AI agent mID, by convention `did:agent:*`.
98    pub fn is_agent(&self) -> bool {
99        self.bearer.starts_with("did:agent:")
100    }
101
102    pub fn expires_within(&self, now: u64, window: u64) -> bool {
103        matches!(self.expiry, Some(e) if e >= now && e - now <= window)
104    }
105}
106
107/// An audit-log entry — who did what, and whether it was allowed.
108#[derive(Clone, Debug, Serialize, Deserialize)]
109pub struct AuditObs {
110    pub actor: String,
111    pub action: String,
112    pub at: u64,
113    pub allowed: bool,
114}
115
116impl AuditObs {
117    pub fn is_agent(&self) -> bool {
118        self.actor.starts_with("did:agent:")
119    }
120}
121
122/// A settled usage receipt — revenue credited to a hosting home for a customer.
123#[derive(Clone, Debug, Serialize, Deserialize)]
124pub struct SettledObs {
125    pub host_did: String,
126    pub settles_to_did: String,
127    pub resource: Resource,
128    pub micro_mata: u64,
129}
130
131/// An agent's remaining spend against its granted budget.
132#[derive(Clone, Debug, Serialize, Deserialize)]
133pub struct AgentBudgetObs {
134    pub agent: String,
135    pub remaining: u64,
136    pub limit: u64,
137}