kcode-k1-accounting 0.1.0

Thread-safe in-memory accounting ledger for exact decimal usage totals.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# kcode-k1-accounting

## Public API

```rust
use std::collections::BTreeMap;

use rust_decimal::Decimal;

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct UsageValue {
    pub units: Decimal,
    pub price_cents: Decimal,
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct AccountingEvent {
    pub source: String,
    pub operation: String,
    pub usage: BTreeMap<String, UsageValue>,
}

#[derive(Clone, Default)]
pub struct Accounting;

impl Accounting {
    pub fn new() -> Self;
    pub fn record(&self, event: &AccountingEvent);
    pub fn entries(&self) -> Vec<AccountingEvent>;
    pub fn totals(&self) -> BTreeMap<String, UsageValue>;
}
```

`UsageValue` accepts every `Decimal` value. `price_cents` is measured in cents and remains an exact decimal value; this library never converts values through floating point.

`record` accepts an empty `usage` map and stores a clone of the event. `entries` returns owned event clones in successful append order. Cloned `Accounting` handles share one ledger. `totals` combines `units` and `price_cents` separately for exact, case-sensitive usage keys across every stored event. Each read is a consistent snapshot: records that append concurrently may be included or omitted. Aggregate decimal overflow panics.

All operations recover and continue with the retained ledger state if its mutex is poisoned. Operations are thread-safe. The only serialization is a brief in-memory ledger lock; no operation performs I/O, retries, or timeout handling.

For an event with `k` usage keys, `record` performs O(k) cloning and an in-memory append. `entries` performs O(total retained data), and `totals` performs O(total retained usage values). The reproducible reference fixture is `cargo test --release --test accounting concurrent_recording` on a supported stable Rust Linux x86_64 environment; it exercises concurrent appends without remote work.