essences/

kill_faucets.rs

//! BAL-038 — persisted daily counter and band snapshot per kill faucet family.
//!
//! Hidden state: the player never sees the counter or the remaining budget. It
//! stays available to telemetry, admin and debug.

use crate::prelude::*;
use chrono::{DateTime, Utc};

/// A reward family with its own counter, band snapshot and cap.
///
/// Equipment Trigger and Effect stones deliberately share ONE counter: the kind
/// is decided by an internal 50/50 roll after the drop is granted, so counting
/// them apart would let a build farm twice the authored budget.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Eq,
    PartialEq,
    Hash,
    Serialize,
    Deserialize,
    JsonSchema,
    Tsify,
    strum::Display,
    strum::EnumString,
    strum::EnumIter,
)]
pub enum KillFaucetFamily {
    /// Five sequential tickets per eligible ordinary campaign-mob death.
    #[default]
    DirectCookies,
    /// `D` is the reached chapter band's `R_value`, not a constant.
    CoreEssence,
    LawCopies,
    /// Trigger + Effect combined, on purpose.
    EquipmentStones,
    /// Campaign mob + boss legs only. The dungeon-clear leg is a separate
    /// faucet and does not consume this counter.
    ArtifactStones,
    /// Skill Crystals paid only by campaign-boss deaths. This family uses an
    /// exact authored daily cap rather than the ordinary `D..2D` decay shape.
    SkillChapters,
    /// Gems paid only by campaign-boss deaths. The exact cap prevents a
    /// repeatable boss farm from becoming an uncapped premium-currency route.
    BossGems,
}

/// The hard cap that belongs to a snapshotted `D`: `ceil(2 × D)`.
///
/// A packet is clipped to the remaining budget rather than allowed to overshoot,
/// so a large packet can never step past the cap.
pub fn hard_cap(d: f64) -> i64 {
    (2.0 * d.max(0.0)).ceil() as i64
}

/// Chance multiplier at `granted` units against a snapshotted `d`, for every
/// family EXCEPT direct Cookies (which keep their own hyperbola).
///
/// Flat `1.0` while `granted <= d`, then continuous linear decay reaching `0` at
/// `2d`. Continuity at `d` matters: a step there would read to a player as the
/// faucet breaking rather than tapering.
pub fn decay_multiplier(granted: f64, d: f64) -> f64 {
    if d <= 0.0 {
        return 0.0;
    }
    ((2.0 * d - granted) / d).clamp(0.0, 1.0)
}

/// One family's day.
///
/// The band (`d`, cap) is SNAPSHOTTED on the first eligible roll after the daily
/// reset and then frozen until the next one. Chapter, mode, build or power
/// progress during the day never reprices it and never restores a chance that
/// has already decayed — otherwise pushing a few chapters mid-session would
/// refresh a spent faucet, which is exactly the unattended-farm loop the cap
/// exists to bound.
///
/// Stored in integers so `CharacterState` keeps its `Eq`: granted units are
/// whole by construction (one Cookie, one stone, `packet` Essence), and `D` is
/// held in micro-units the way BAL-021 holds Plinko tranches.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Tsify)]
pub struct KillFaucetDailyState {
    /// Units actually GRANTED today, not roll attempts. A proc clipped to the
    /// remaining budget counts only what it paid out.
    pub granted: i64,
    /// Snapshotted `D` in micro-units (`D × 1_000_000`).
    pub d_micro: i64,
    /// Snapshotted `ceil(2 × D)`.
    pub cap: i64,
    pub last_reset_at: DateTime<Utc>,
}

/// Fixed-point scale for [`KillFaucetDailyState::d_micro`].
pub const D_MICRO: i64 = 1_000_000;

impl KillFaucetDailyState {
    /// Open a fresh day for a family whose band resolves to `d`.
    pub fn snapshot(d: f64, now: DateTime<Utc>) -> Self {
        Self {
            granted: 0,
            d_micro: (d.max(0.0) * D_MICRO as f64).round() as i64,
            cap: hard_cap(d),
            last_reset_at: now,
        }
    }

    /// The snapshotted `D` back in natural units.
    pub fn d(&self) -> f64 {
        self.d_micro as f64 / D_MICRO as f64
    }

    /// Budget still payable today. Zero means the family is done until reset.
    pub fn remaining(&self) -> i64 {
        (self.cap - self.granted).max(0)
    }

    /// Chance multiplier for a non-Cookie family at the current `granted`.
    pub fn decay(&self) -> f64 {
        decay_multiplier(self.granted as f64, self.d())
    }

    /// Clip `amount` to the remaining budget and bank it. Returns what was
    /// actually paid, which is what the caller must grant — never the request.
    pub fn take(&mut self, amount: i64) -> i64 {
        let paid = amount.max(0).min(self.remaining());
        self.granted += paid;
        paid
    }
}

pub type KillFaucetDailyMap = std::collections::HashMap<KillFaucetFamily, KillFaucetDailyState>;

/// The family's state for TODAY, snapshotting the band if this is its first
/// eligible roll since the daily reset.
///
/// The reset is lazy on purpose: it is a pure function of the stored
/// `last_reset_at` against `now`, evaluated when a roll actually happens. That
/// keeps it inside the deterministic handler, needs no separate reset event, and
/// lines up with the authoritative quests/ads daily boundary because both
/// compare calendar dates.
///
/// An already-open day is returned UNCHANGED even when `d_today` differs — that
/// is the anti-repricing invariant. Progressing chapters mid-session must not
/// raise `D`, refresh the cap, or restore a chance that has already decayed.
pub fn band_for_today(
    map: &mut KillFaucetDailyMap,
    family: KillFaucetFamily,
    d_today: f64,
    now: DateTime<Utc>,
) -> &mut KillFaucetDailyState {
    let stale = map
        .get(&family)
        .is_none_or(|s| s.last_reset_at.date_naive() < now.date_naive());
    if stale {
        map.insert(family, KillFaucetDailyState::snapshot(d_today, now));
    }
    map.get_mut(&family).expect("just inserted")
}

/// The family's state for today with an exact hard cap.
///
/// Boss-only currency budgets are authored as a final daily amount, not as the
/// knee of a diminishing `D..2D` curve. The value is still snapshotted on the
/// first eligible boss death and never repriced within the day.
pub fn exact_cap_for_today(
    map: &mut KillFaucetDailyMap,
    family: KillFaucetFamily,
    cap_today: i64,
    now: DateTime<Utc>,
) -> &mut KillFaucetDailyState {
    let stale = map
        .get(&family)
        .is_none_or(|s| s.last_reset_at.date_naive() < now.date_naive());
    if stale {
        let cap = cap_today.max(0);
        map.insert(
            family,
            KillFaucetDailyState {
                granted: 0,
                d_micro: cap.saturating_mul(D_MICRO),
                cap,
                last_reset_at: now,
            },
        );
    }
    map.get_mut(&family).expect("just inserted")
}

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

    fn t0() -> DateTime<Utc> {
        DateTime::<Utc>::from_timestamp(0, 0).unwrap()
    }

    #[test]
    fn a_packet_is_clipped_to_the_remaining_budget() {
        // laws: D = 5.659 -> cap 12. A packet may never step past the cap.
        let mut s = KillFaucetDailyState::snapshot(5.659, t0());
        assert_eq!(s.cap, 12);
        assert_eq!(s.take(11), 11);
        assert_eq!(s.take(5), 1, "clipped to what is left, not the request");
        assert_eq!(s.remaining(), 0);
        assert_eq!(s.take(1), 0, "capped means capped");
    }

    #[test]
    fn decay_starts_at_the_knee_not_at_zero() {
        let mut s = KillFaucetDailyState::snapshot(42.14, t0());
        assert_eq!(s.decay(), 1.0);
        s.take(42);
        assert!(s.decay() > 0.99, "flat through D, continuous at the knee");
        s.take(43);
        assert_eq!(s.decay(), 0.0, "zero at 2D");
    }
}

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

    fn day(n: i64) -> DateTime<Utc> {
        DateTime::<Utc>::from_timestamp(n * 86_400, 0).unwrap()
    }

    #[test]
    fn an_open_day_is_never_repriced_by_chapter_progress() {
        let mut map = KillFaucetDailyMap::new();
        // First roll of the day in the ch21 band.
        let s = band_for_today(&mut map, KillFaucetFamily::CoreEssence, 1_000.0, day(1));
        assert_eq!(s.cap, 2_000);
        s.take(1_500);

        // The player pushes into the ch52 band the same day. D must NOT rise,
        // the cap must not grow, and the spent budget must not come back.
        let s = band_for_today(&mut map, KillFaucetFamily::CoreEssence, 1_500.0, day(1));
        assert_eq!(
            s.cap, 2_000,
            "intraday band change must not reprice the day"
        );
        assert_eq!(s.granted, 1_500);
        assert_eq!(s.remaining(), 500);
    }

    #[test]
    fn the_next_day_snapshots_the_new_band() {
        let mut map = KillFaucetDailyMap::new();
        band_for_today(&mut map, KillFaucetFamily::CoreEssence, 1_000.0, day(1)).take(2_000);

        let s = band_for_today(&mut map, KillFaucetFamily::CoreEssence, 1_500.0, day(2));
        assert_eq!(s.cap, 3_000, "a fresh day takes the CURRENT band");
        assert_eq!(s.granted, 0);
    }

    #[test]
    fn an_exact_cap_never_uses_the_two_d_headroom() {
        let mut map = KillFaucetDailyMap::new();
        let s = exact_cap_for_today(&mut map, KillFaucetFamily::SkillChapters, 45, day(1));
        assert_eq!(s.cap, 45);
        assert_eq!(s.take(44), 44);
        assert_eq!(s.take(2), 1);
        assert_eq!(s.remaining(), 0);
    }
}