conservation-checker

One-sided conservation laws for real systems.

Track quantities that must not decrease across operations — budgets, energy, quotas, token counts, throughput — with tolerance, drift detection, and phase analysis.

30-Second Example

use conservation_checker::ConservationChecker;

let mut checker = ConservationChecker::new();

// Register a quantity: name, initial value, allowed decrease (tolerance)
checker.register("energy", 100.0, 5.0);

// Update as your system runs
checker.update("energy", 98.0);  // still conserved
checker.snapshot();

checker.update("energy", 90.0);  // dropped past tolerance!
checker.snapshot();

assert!(!checker.is_conserved("energy"));
assert_eq!(checker.violations(), vec!["energy"]);

Why?

Conservation laws aren't just physics. Real systems have quantities that should only increase or stay flat:

Budget tracking — spending must not exceed allocation
API rate limits — request count must not exceed quota
Energy monitoring — battery drain beyond expected range signals problems
Token budgets — LLM token consumption against a cap
Throughput quotas — data transfer against a monthly limit

conservation-checker gives you a simple, zero-dependency way to assert these invariants, detect when they're violated, and track trends over time.

Real Use Cases

Budget Tracking

let mut budget = ConservationChecker::new();
budget.register("monthly", 5000.0, 100.0); // $100 buffer

for expense in &expenses {
    let remaining = budget.current_value("monthly") - expense;
    budget.update("monthly", remaining);
    budget.snapshot();
}

if !budget.violations().is_empty() {
    println!("⚠️ Over budget!");
}

API Rate Limits

let mut limits = ConservationChecker::new();
limits.register("requests_remaining", 10000.0, 0.0);

// After each API call:
limits.update("requests_remaining", remaining_count);
limits.snapshot();

if limits.phase("requests_remaining") == Phase::Transitioning {
    println!("Rate limit approaching — slow down!");
}

Energy Monitoring

let mut monitor = ConservationChecker::new();
monitor.register("battery", 100.0, 20.0); // 20% tolerance

monitor.update("battery", current_level);
monitor.snapshot();

let drain = monitor.drift_rate("battery"); // % per tick
println!("Battery drain: {:.1}%/tick", drain);

Token Budgets

let mut tokens = ConservationChecker::new();
tokens.register("token_cap", 4096.0, 0.0);

tokens.update("token_cap", tokens_used);
if !tokens.is_conserved("token_cap") {
    return Err("Token budget exceeded!");
}

API Reference

`ConservationChecker`

Method	Description
`new()`	Create an empty tracker
`register(name, initial, tolerance)`	Register a quantity with initial value and allowed decrease
`update(name, value)`	Set the current value of a quantity
`is_conserved(name) -> bool`	Check if value ≥ initial − tolerance
`violations() -> Vec<String>`	List all quantities currently violated
`snapshot()`	Record current values into history
`phase(name) -> Phase`	Detect trajectory phase from history
`drift_rate(name) -> f64`	Average change per snapshot
`current_value(name) -> f64`	Get the current value
`initial_value(name) -> f64`	Get the initial (baseline) value
`snapshot_count(name) -> usize`	Number of snapshots recorded
`registered() -> Vec<String>`	All registered quantity names
`deregister(name) -> bool`	Remove a quantity
`reset_baseline(name)`	Reset initial value to current, clearing violations

`Phase`

pub enum Phase {
    Stable,          // No significant change
    PreTransition,   // Accelerating but not yet violated
    Transitioning,   // Actively decreasing past tolerance
    Resolving,       // Was violated, now recovering
}

Design Principles

Zero dependencies — nothing to audit, nothing to break
#![deny(unsafe_code)] — memory safety guaranteed
One-sided — increases are always OK, only decreases can violate
Tolerance-aware — real systems have acceptable ranges, not exact values
Time-series built in — snapshot history enables drift and phase detection

Running Examples

cargo run --example basic
cargo run --example budget_tracking

License

MIT

conservation-checker 0.1.0