monetize-product 0.3.2

//! **The estate guardian lane** (5.4 resilience): what a product knows about repairing one
//! of its estates, as a PLAN — never as a call into the estate.
//!
//! Monetize never calls INTO an estate. The estate's boxes report (`Fleet.Report`), and the
//! guardian reads those reports, opens a case, takes a human's button (or the estate's
//! auto-fix opt-in), does the CLOUD part itself through `monetize_cloud::Cloud`
//! (fence, lay), and queues SIGNED orders that the boxes pull and run through the product's
//! own repair verbs (gunnar: `gunnar-repair`) — the same functions their local admin button
//! and their boot check run. This trait is the product's half: diagnose, plan, observe.
//! The runner (cases, approvals, the order queue, the fence invariant) is
//! `monetize-guardian`, shared by every product.
//!
//! It replaced the dial-in restore and twinship lanes, which are gone (no legacy).

use std::collections::BTreeMap;

/// The guard before a main's data is destroyed (Gunnar's `rebuild::judge`, R1–R6), shared by
/// every product's guardian (lane G11).
pub mod rebuild;

/// The plan's building blocks every product's guardian writes the same way (P4a): `order`,
/// `wait`, `recharge`, `restate`, `heard`, `word` and the three bounds.
pub mod steps;

/// The roles of an estate's boxes.
pub mod role {
    pub const MAIN: &str = "main";
    pub const TWIN: &str = "twin";
    pub const FRONT: &str = "front";
}

/// **The buttons** — one per repair the guardian can drive.
#[derive(
    Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, serde::Serialize, serde::Deserialize,
)]
#[serde(rename_all = "snake_case")]
pub enum Remedy {
    /// The main's data is lost or diverged: the twin's log is pumped into it (a fresh main
    /// first when the old box is gone).
    RechargeFromTwin,
    /// The primary reviews its twin and reports the `TwinReview`. Nothing changes.
    ReviewTwin,
    /// The twin is gone: a new box is laid, installed, and the primary adopts it.
    NewTwin,
    /// The main is gone: a new box is laid, installed, and recharged from the twin.
    NewServer,
    /// The front is lost: restored from its provider's daily backup (S8, 2026-10-11) — its own
    /// keys kept, nothing re-trusted. No backup: refused; the front is re-laid by hand (OM-6).
    RestoreFront,
}

impl Remedy {
    pub const ALL: [Remedy; 5] = [
        Remedy::RechargeFromTwin,
        Remedy::ReviewTwin,
        Remedy::NewTwin,
        Remedy::NewServer,
        Remedy::RestoreFront,
    ];

    pub fn as_str(self) -> &'static str {
        match self {
            Remedy::RechargeFromTwin => "recharge_from_twin",
            Remedy::ReviewTwin => "review_twin",
            Remedy::NewTwin => "new_twin",
            Remedy::NewServer => "new_server",
            Remedy::RestoreFront => "restore_front",
        }
    }

    pub fn parse(s: &str) -> Option<Remedy> {
        Remedy::ALL.into_iter().find(|r| r.as_str() == s)
    }

    /// The button's words.
    pub fn words(self) -> &'static str {
        match self {
            Remedy::RechargeFromTwin => "Recharge from twin",
            Remedy::ReviewTwin => "Review twin",
            Remedy::NewTwin => "New twin",
            Remedy::NewServer => "New server",
            Remedy::RestoreFront => "Restore front from backup",
        }
    }
}

/// One box as monetize last HEARD it — nothing here was dialled.
#[derive(Clone, PartialEq, Eq, Debug, Default, serde::Serialize, serde::Deserialize)]
#[serde(default)]
pub struct BoxView {
    pub role: String,
    /// When its newest `Fleet.Report` arrived (unix ms); 0: never heard.
    pub heard_unix_ms: u64,
    pub build: String,
    /// The box's own health words, flat (`serving`, `data`, `serves_at`, `twin`, …).
    pub health: BTreeMap<String, String>,
    /// The product's twin review as the box last reported it (JSON text), empty when none.
    pub twin_review: String,
    /// The orders it acked, newest last.
    pub acks: Vec<AckView>,
    /// Where the cloud laid it (its utility IPv4), empty when monetize laid nothing.
    pub laid_ipv4: String,
    /// What the provider says of the box, when the runner asked (`active`, `stopped`,
    /// `gone`); empty: not asked.
    pub at_provider: String,
}

impl BoxView {
    /// Silent: never heard, or not heard for `silent_after_ms`.
    pub fn silent(&self, now_unix_ms: u64, silent_after_ms: u64) -> bool {
        self.heard_unix_ms == 0 || now_unix_ms.saturating_sub(self.heard_unix_ms) > silent_after_ms
    }

    pub fn word(&self, key: &str) -> &str {
        self.health.get(key).map(String::as_str).unwrap_or("")
    }
}

/// One order a box acked.
#[derive(Clone, PartialEq, Eq, Debug, Default, serde::Serialize, serde::Deserialize)]
#[serde(default)]
pub struct AckView {
    pub seq: u64,
    pub kind: String,
    pub ok: bool,
    pub detail: String,
}

/// **One estate, as the guardian sees it**: its boxes by role, read from reports.
#[derive(Clone, PartialEq, Eq, Debug, Default, serde::Serialize, serde::Deserialize)]
#[serde(default)]
pub struct EstateView {
    pub product: String,
    pub instance: String,
    pub now_unix_ms: u64,
    /// A box not heard for this long is silent (3 report intervals).
    pub silent_after_ms: u64,
    pub boxes: BTreeMap<String, BoxView>,
}

impl EstateView {
    pub fn get(&self, role: &str) -> Option<&BoxView> {
        self.boxes.get(role)
    }

    /// The box in `role` is silent (or was never heard, or does not exist).
    pub fn silent(&self, role: &str) -> bool {
        self.boxes
            .get(role)
            .is_none_or(|b| b.silent(self.now_unix_ms, self.silent_after_ms))
    }
}

/// **What is wrong**, with what shows it.
#[derive(Clone, PartialEq, Eq, Debug, Default, serde::Serialize, serde::Deserialize)]
#[serde(default)]
pub struct Finding {
    /// Stable code: `twin_lost`, `main_lost`, `main_data_lost`, …
    pub code: String,
    /// The box it is about.
    pub role: String,
    /// One sentence for the case screen.
    pub words: String,
    /// The reported facts it rests on.
    pub evidence: Vec<String>,
    /// The buttons that answer it, the recommended first.
    pub remedies: Vec<Remedy>,
    /// What auto-fix (when the estate opted in) may take on its own; `None`: only a human.
    pub auto: Option<Remedy>,
}

/// The cloud half of a step: done by the runner through `Cloud`, never by the estate.
#[derive(Clone, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CloudStep {
    /// The role's old box given back WHOLE — its server (stopped by the provider's destroy),
    /// every disk and its release clone, as the laid record names them — until the
    /// provider's own listing holds none of it (`Change::Retire`). Idempotent.
    Fence { role: String },
    /// One box laid again for `role` through the shop's lay + installer path. The runner
    /// refuses it while anything of the role's old box still stands, or cannot be looked
    /// up (the fence invariant).
    Lay { role: String },
    /// The role's box restored from its provider's newest backup (S8: the FRONT, whose disk
    /// holds the estate's keys) — in place, or made again from the backup at a new address.
    /// Lays nothing; the shop's own restore path (`World::restore_one`).
    Restore { role: String },
}

/// **One step of a plan.**
#[derive(Clone, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Step {
    Cloud(CloudStep),
    /// A signed order queued for the box in `role`; met when it acks `ok`, failed when it
    /// acks not ok. String values `$addr:<role>` in `body` are filled in when queued with
    /// that box's address (its `serves_at`, else its laid IPv4); `$epoch` with the case's
    /// fence epoch; `$principal` with who approved.
    Order {
        role: String,
        kind: String,
        body: BTreeMap<String, String>,
    },
    /// Wait for the estate to show something: `heard` (a report from `role` newer than the
    /// step) is the runner's; anything else is [`EstateGuardian::observe`]'s.
    Await {
        role: String,
        what: String,
        within_ms: u64,
    },
}

impl Step {
    pub fn words(&self) -> String {
        match self {
            Step::Cloud(CloudStep::Fence { role }) => {
                format!("fence {role} (server and disks given back, read back gone)")
            }
            Step::Cloud(CloudStep::Lay { role }) => format!("lay a new {role} (installer)"),
            Step::Cloud(CloudStep::Restore { role }) => {
                format!("restore {role} from its daily backup")
            }
            Step::Order { role, kind, .. } => format!("order {kind} → {role}"),
            Step::Await { role, what, .. } => format!("await {role} {what}"),
        }
    }
}

/// What [`EstateGuardian::observe`] says of an `Await`.
#[derive(Clone, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum StepState {
    Waiting(String),
    Met(String),
    Failed(String),
}

/// **The product's guardian**: pure functions over what the estate reported.
pub trait EstateGuardian: Send + Sync {
    /// What is wrong now. Empty: nothing.
    fn diagnose(&self, view: &EstateView) -> Vec<Finding>;
    /// The steps that carry out `remedy` on this estate, or why it may not run now.
    fn plan(&self, remedy: Remedy, view: &EstateView) -> Result<Vec<Step>, String>;
    /// Is the `Await` step met? The runner answers `heard` itself and never asks.
    fn observe(&self, role: &str, what: &str, view: &EstateView) -> StepState;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_remedy_round_trips_its_wire_name() {
        for r in Remedy::ALL {
            assert_eq!(Remedy::parse(r.as_str()), Some(r));
        }
        assert_eq!(Remedy::parse("rollback"), None);
        assert_eq!(serde_json_like(Remedy::NewTwin), "new_twin");
    }

    fn serde_json_like(r: Remedy) -> &'static str {
        r.as_str()
    }

    #[test]
    fn a_box_never_heard_is_silent_and_a_fresh_one_is_not() {
        let mut v = EstateView {
            now_unix_ms: 100_000,
            silent_after_ms: 30_000,
            ..Default::default()
        };
        assert!(v.silent("twin"));
        v.boxes.insert(
            "twin".into(),
            BoxView {
                role: "twin".into(),
                heard_unix_ms: 90_000,
                ..Default::default()
            },
        );
        assert!(!v.silent("twin"));
        v.now_unix_ms = 121_000;
        assert!(v.silent("twin"));
    }
}