karma-cigarette 0.1.0

Deterministic karma ledgers and net settlement by the Cocoshiga principle
Documentation
  • Coverage
  • 100%
    35 out of 35 items documented1 out of 30 items with examples
  • Size
  • Source code size: 18.1 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 426.1 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • hidenoriuehara-art

karma-cigarette

karma-cigarette is a small, dependency-free Rust library for recording interpersonal contributions and turning them into deterministic net settlements.

The Cocoshiga principle

This crate gives a concrete meaning to 業清算のココシガの理:

Do not replay every act. Preserve the whole, cancel reciprocal karma, and settle only the remainder here and now.

When Alice gives 10 units to Bob, Bob owes Alice 10 units. If Bob later gives 4 units to Alice, only 6 units remain. In a larger group, the same conservation rule produces a compact list of transfers without changing anybody's net position.

This is an application-level accounting model, not financial, legal, or moral advice.

Example

use karma_cigarette::{Cocoshiga, KarmaLedger};

let mut ledger = KarmaLedger::new();
ledger.record("alice", "bob", 10, "covered lunch")?;
ledger.record("bob", "alice", 4, "bought coffee")?;
ledger.record("carol", "bob", 3, "shared work")?;

let plan = Cocoshiga::settle(&ledger)?;

assert_eq!(plan.total_units(), 9);
assert!(plan.is_conserved());

# Ok::<(), karma_cigarette::KarmaError>(())

Semantics

  • A recorded contribution increases the giver's receivable balance.
  • A positive balance means the party should receive units.
  • A negative balance means the party should pay units.
  • Reciprocal and transitive obligations are netted.
  • Settlement order is deterministic because party identifiers are ordered.
  • Empty names, self-directed entries, zero-unit entries, and arithmetic overflow are rejected.

License

MIT