zc2 0.0.48

P2P compute broker with yen-denominated billing, WAL, and broker mesh support
//! What a batch reserves, and what it finally owes.
//!
//! One reservation for the whole batch, not one per task. On a mesh where the
//! requester's ledger lives on another broker, a reservation is a synchronous
//! round trip — so per-task reservations would put the very cost batching
//! exists to remove back into every task. At fifty tasks a batch this is 98% of
//! the billing traffic.
//!
//! The invariants worth stating, because each is a way to lose money:
//!
//! - the reservation is a CEILING, never a charge;
//! - a task that never ran is never charged;
//! - the total settled never exceeds what was reserved, however long a worker
//!   overran — the reservation is the requester's exposure and it was agreed
//!   before anything ran.

/// A batch's money, from the estimate to the settlement.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct BatchBill {
    reserved: f64,
    /// Every task the batch contains, and what it cost once it finished.
    ///
    /// Pre-populated with the batch's ids at `None`, so the map distinguishes
    /// the three states that matter: a task that finished and costs something,
    /// a task that never finished and costs nothing, and an id that was never
    /// in this batch at all and cannot be billed.
    actuals: std::collections::BTreeMap<u32, Option<f64>>,
}

/// Why a batch could not be admitted.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum BillError {
    /// The requester cannot cover even the reduced batch.
    Insufficient,
}

/// Decide what to hold for a batch.
///
/// The reservation is the smallest of what the work is estimated to cost, what
/// the caller said they would spend, and what they actually have. Holding more
/// than the balance is the overspend path: the hold succeeds, the work runs,
/// and settlement discovers the shortfall with the compute already spent.
pub(crate) fn plan(
    estimates: &[(u32, f64)],
    budget: Option<f64>,
    balance: f64,
) -> Result<BatchBill, BillError> {
    let wanted: f64 = estimates
        .iter()
        .map(|(_, c)| c)
        .filter(|c| c.is_finite() && **c > 0.0)
        .sum();
    let capped = match budget {
        Some(b) if b.is_finite() && b > 0.0 => wanted.min(b),
        _ => wanted,
    };
    // An empty batch asks for nothing and cannot be refused for it.
    let actuals = estimates.iter().map(|(id, _)| (*id, None)).collect();
    if capped == 0.0 {
        return Ok(BatchBill {
            reserved: 0.0,
            actuals,
        });
    }
    // Explicitly NaN-safe: `balance <= 0.0` is false for NaN, which would
    // admit a batch against a balance nobody can read.
    if !balance.is_finite() || balance <= 0.0 {
        return Err(BillError::Insufficient);
    }
    Ok(BatchBill {
        reserved: capped.min(balance),
        actuals,
    })
}

impl BatchBill {
    /// What was held for this batch.
    pub(crate) fn reserved(&self) -> f64 {
        self.reserved
    }

    /// Note what a finished task actually cost.
    ///
    /// Silently ignores what cannot be a cost — an id this batch never
    /// contained (a confused peer, or a replayed frame), and a negative or
    /// non-finite figure (a broken one). Neither is a discount and neither is
    /// a charge; folding either in would bill the requester on a number nobody
    /// stands behind.
    pub(crate) fn record(&mut self, id: u32, actual: f64) {
        if !actual.is_finite() || actual < 0.0 {
            return;
        }
        if let Some(slot) = self.actuals.get_mut(&id) {
            *slot = Some(actual);
        }
    }

    /// What the batch owes: what actually ran, capped by what was held.
    pub(crate) fn settle(&self) -> f64 {
        let spent: f64 = self.actuals.values().flatten().sum();
        spent.min(self.reserved)
    }

    /// What to release back to the requester. With [`settle`](Self::settle) it
    /// adds up to the reservation exactly, so a batch never leaks money.
    pub(crate) fn refund(&self) -> f64 {
        self.reserved - self.settle()
    }
}

/// Most task samples one batch's metadata carries.
pub(crate) const MAX_TRUST_SAMPLES: usize = 25;

/// The real-job evidence one batch leaves on its earn row, for the hub's
/// node-trust check (spec: benchmark vs real jobs).
///
/// A batch settles as ONE transaction, so the per-task facts ride in a list:
/// `{"tasks": [{"payload_sha256": <hex of the cloudpickle bytes>, "service_ms":
/// <u64>}, ...]}`. The hub compares nodes that ran the SAME payload hash.
/// `service_ms` is the worker's own elapsed time, rounded to whole ms; a
/// non-finite or negative figure is recorded as 0 rather than dropped.
pub(crate) fn trust_metadata<'a>(
    ran: impl IntoIterator<Item = (&'a [u8], f64)>,
) -> serde_json::Value {
    let ran: Vec<_> = ran.into_iter().collect();
    // A batch can hold 10,000 tasks (~1.1 MB of metadata) and the trust check
    // needs ~20 pairs per node over 7 days (not per batch), and 200-sample
    // rows pushed a 500-row flush chunk past the hub's 1 MiB limit (#330). So
    // keep a deterministic spread of at most MAX_TRUST_SAMPLES: every ceil(n/MAX)-th task, so distinct payloads
    // across the batch stay represented.
    let step = ran.len().div_ceil(MAX_TRUST_SAMPLES).max(1);
    let tasks: Vec<serde_json::Value> = ran
        .into_iter()
        .step_by(step)
        .map(|(payload, ms)| {
            let service_ms = if ms.is_finite() && ms > 0.0 {
                ms.round() as u64
            } else {
                0
            };
            serde_json::json!({
                "payload_sha256": hex::encode(ring::digest::digest(&ring::digest::SHA256, payload)),
                "service_ms": service_ms,
            })
        })
        .collect();
    serde_json::json!({ "tasks": tasks })
}

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

    const PLENTY: f64 = 1_000.0;

    fn est(n: u32, each: f64) -> Vec<(u32, f64)> {
        (0..n).map(|i| (i, each)).collect()
    }

    #[test]
    fn a_batch_reserves_the_sum_of_its_estimates() {
        let bill = plan(&est(50, 0.001), None, PLENTY).unwrap();
        assert!((bill.reserved() - 0.05).abs() < 1e-9, "{}", bill.reserved());
    }

    /// The budget is a per-batch ceiling. A batch that estimates past it is
    /// held at the ceiling rather than refused — the tasks that fit still run,
    /// and settlement charges only what ran.
    #[test]
    fn the_budget_caps_the_reservation() {
        let bill = plan(&est(50, 0.001), Some(0.01), PLENTY).unwrap();
        assert!((bill.reserved() - 0.01).abs() < 1e-9, "{}", bill.reserved());
    }

    /// A requester can never have more held than they have. Without this the
    /// reservation succeeds and settlement discovers the shortfall, which is
    /// the overspend path.
    #[test]
    fn the_balance_caps_the_reservation() {
        let bill = plan(&est(50, 0.001), None, 0.004).unwrap();
        assert!(
            (bill.reserved() - 0.004).abs() < 1e-9,
            "{}",
            bill.reserved()
        );
    }

    #[test]
    fn a_requester_with_nothing_is_refused() {
        assert_eq!(
            plan(&est(10, 0.001), None, 0.0),
            Err(BillError::Insufficient)
        );
        assert_eq!(
            plan(&est(10, 0.001), None, -1.0),
            Err(BillError::Insufficient)
        );
    }

    /// An empty batch is legal and holds nothing.
    #[test]
    fn an_empty_batch_reserves_nothing() {
        assert_eq!(plan(&[], None, PLENTY).unwrap().reserved(), 0.0);
    }

    #[test]
    fn the_batch_owes_what_actually_ran() {
        let mut bill = plan(&est(3, 0.010), None, PLENTY).unwrap();
        bill.record(0, 0.004);
        bill.record(1, 0.006);
        bill.record(2, 0.005);
        assert!((bill.settle() - 0.015).abs() < 1e-9, "{}", bill.settle());
    }

    /// The case a dropped connection produces: two of three finished. The
    /// third never ran as far as anyone knows, and charging for it would be
    /// charging for work nobody did.
    #[test]
    fn a_task_that_never_finished_is_never_charged() {
        let mut bill = plan(&est(3, 0.010), None, PLENTY).unwrap();
        bill.record(0, 0.004);
        bill.record(1, 0.006);
        assert!((bill.settle() - 0.010).abs() < 1e-9, "{}", bill.settle());
    }

    /// The reservation is the requester's agreed exposure. A worker that
    /// overran cannot charge past it — that overspend is the executor's
    /// problem to raise, not something to take silently.
    #[test]
    fn settlement_never_exceeds_what_was_reserved() {
        let mut bill = plan(&est(2, 0.001), None, PLENTY).unwrap();
        assert!((bill.reserved() - 0.002).abs() < 1e-9);
        bill.record(0, 5.0);
        bill.record(1, 5.0);
        assert!((bill.settle() - 0.002).abs() < 1e-9, "{}", bill.settle());
    }

    /// What goes back: everything held that was not spent. The two must add up
    /// to the reservation exactly, or a batch leaks money every time it runs.
    #[test]
    fn what_is_spent_and_what_is_returned_add_up_to_what_was_held() {
        let mut bill = plan(&est(4, 0.010), None, PLENTY).unwrap();
        bill.record(0, 0.004);
        bill.record(2, 0.006);
        assert!(
            (bill.settle() + bill.refund() - bill.reserved()).abs() < 1e-9,
            "spent {} + returned {} != held {}",
            bill.settle(),
            bill.refund(),
            bill.reserved()
        );
    }

    /// A result for a task the batch never contained is not billable. It means
    /// a confused peer or a replayed frame, and folding it in would charge the
    /// requester for work they did not ask for.
    #[test]
    fn a_result_for_an_unknown_task_is_not_charged() {
        let mut bill = plan(&est(2, 0.010), None, PLENTY).unwrap();
        bill.record(0, 0.004);
        bill.record(999, 5.0);
        assert!((bill.settle() - 0.004).abs() < 1e-9, "{}", bill.settle());
    }

    /// Frames can be redelivered. The second result for a task must replace
    /// the first, not add to it.
    #[test]
    fn a_repeated_result_replaces_rather_than_accumulates() {
        let mut bill = plan(&est(1, 0.010), None, PLENTY).unwrap();
        bill.record(0, 0.004);
        bill.record(0, 0.004);
        assert!((bill.settle() - 0.004).abs() < 1e-9, "{}", bill.settle());
    }

    /// A negative or non-finite cost is a broken peer, not a discount.
    #[test]
    fn a_nonsense_cost_is_ignored_rather_than_believed() {
        let mut bill = plan(&est(2, 0.010), None, PLENTY).unwrap();
        bill.record(0, -5.0);
        bill.record(1, f64::NAN);
        assert_eq!(bill.settle(), 0.0);
    }

    #[test]
    fn earn_metadata_carries_payload_hash_and_service_ms() {
        let m = trust_metadata([(&b"abc"[..], 123.6), (&b"abc"[..], f64::NAN)]);
        let t = m["tasks"].as_array().unwrap();
        assert_eq!(
            t[0]["payload_sha256"],
            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
        );
        assert_eq!(t[0]["service_ms"], 124);
        assert_eq!(t[1]["service_ms"], 0);
    }

    #[test]
    fn earn_metadata_samples_at_most_25_tasks_spread_across_the_batch() {
        let payloads: Vec<Vec<u8>> = (0..10_000u32).map(|i| i.to_le_bytes().to_vec()).collect();
        let m = trust_metadata(payloads.iter().map(|p| (p.as_slice(), 5.0)));
        let t = m["tasks"].as_array().unwrap();
        assert!(
            t.len() <= 25 && t.len() <= MAX_TRUST_SAMPLES && t.len() >= 13,
            "{}",
            t.len()
        );
        let distinct: std::collections::BTreeSet<_> = t
            .iter()
            .map(|x| x["payload_sha256"].as_str().unwrap())
            .collect();
        assert_eq!(distinct.len(), t.len());
        let small = trust_metadata(payloads.iter().take(7).map(|p| (p.as_slice(), 5.0)));
        assert_eq!(small["tasks"].as_array().unwrap().len(), 7);
    }
}