GitHub - abokhalill/cuttlefish: Coordination-free distributed state kernel with nanosecond latency

Fact → Bloom Clock → Invariant → Frontier → Gossip
286ns admission. 3.5M ops/sec. Zero consensus. Full observability.

[dependencies]
ctfs = "1.0.2"
zerocopy = "0.8"

use ctfs::prelude::*;
use ctfs::invariants::total_supply::{ConservationState, TotalSupplyInvariant};
use zerocopy::IntoBytes;

fn main() {
    // Initialize: balance=0, bounds=[MIN, MAX]
    let state = ConservationState::new(0, i128::MIN, i128::MAX);
    let mut cell = StateCell::new();
    cell.as_slice_mut().copy_from_slice(state.as_bytes());

    let mut kernel = Kernel::with_state(TotalSupplyInvariant::new(), cell);

    // Admit a fact: +100 to balance
    let fact_id: FactId = [0u8; 32];
    let payload = 100i128.to_le_bytes();
    kernel.admit_raw(&fact_id, &[], &payload).unwrap();
}

┌─────────────────────────────────────────────────────────────┐
│                         Kernels                             │
├─────────────┬─────────────┬─────────────┬───────────────────┤
│   Kernel    │ TwoLane     │ Escalating  │ Durable/Network   │
│   (basic)   │ (BFVC+Exact)│ (auto-mode) │ (io_uring/gossip) │
├─────────────┴─────────────┴─────────────┴───────────────────┤
│                      Causal Layer                           │
├─────────────┬─────────────┬─────────────────────────────────┤
│ CausalClock │ PreciseClock│ ExactCausalIndex                │
│ (512b Bloom)│ (LRU exact) │ (Robin Hood, SIMD)              │
├─────────────┴─────────────┴─────────────────────────────────┤
│                    Invariant Layer                          │
├─────────────┬─────────────┬─────────────┬───────────────────┤
│ TotalSupply │ Max/GCounter│ Uniqueness  │ GGraph            │
│ (conserve)  │ (monotonic) │ (idempotent)│ (grow-only graph) │
├─────────────┴─────────────┴─────────────┴───────────────────┤
│                   Persistence Layer                         │
├─────────────┬─────────────┬─────────────────────────────────┤
│  WALArena   │ SPSC Buffer │ io_uring Worker                 │
│ (zero-copy) │ (lock-free) │ (async fsync)                   │
├─────────────┴─────────────┴─────────────────────────────────┤
│                   Checkpoint Layer                          │
├─────────────────────────────────────────────────────────────┤
│ Tiered BLAKE3 Hash │ Attestation │ Re-anchoring             │
└─────────────────────────────────────────────────────────────┘

cargo run --example basic_kernel      # Basic fact admission and causality
cargo run --example multi_tenant      # Isolated causal domains per tenant
cargo run --example custom_invariant  # Implement your own invariant
cargo run --example two_lane_kernel   # BFVC + ExactCausalIndex
cargo run --example escalating_kernel # Auto-switch Bloom → Precise mode
cargo run --example graph_invariant   # Grow-only graph with constraints

use ctfs::core::{Kernel, StateCell};
use ctfs::core::topology::FactId;
use ctfs::invariants::total_supply::{ConservationState, TotalSupplyInvariant};
use zerocopy::IntoBytes;

fn main() {
    // Initialize state
    let state = ConservationState::new(1000, 0, 1_000_000);
    let mut cell = StateCell::new();
    cell.as_slice_mut().copy_from_slice(state.as_bytes());

    let mut kernel = Kernel::with_state(TotalSupplyInvariant::new(), cell);

    // Admit facts
    let fact1: FactId = [1u8; 32];
    kernel.admit_raw(&fact1, &[], &500i128.to_le_bytes()).unwrap();

    // Admit with causal dependency
    let fact2: FactId = [2u8; 32];
    kernel.admit_raw(&fact2, &[fact1], &(-200i128).to_le_bytes()).unwrap();
}

use ctfs::core::{Invariant, InvariantError};

struct MonotonicInvariant;

impl Invariant for MonotonicInvariant {
    fn apply(&self, payload: &[u8], state: &mut [u8]) -> Result<(), InvariantError> {
        let proposed = u64::from_le_bytes(payload[0..8].try_into().unwrap());
        let current = u64::from_le_bytes(state[0..8].try_into().unwrap());
        
        if proposed < current {
            return Err(InvariantError::Underflow);
        }
        state[0..8].copy_from_slice(&proposed.to_le_bytes());
        Ok(())
    }
}

// Non-blocking: returns immediately with a handle
let handle = kernel.admit_async(&fact_id, &deps, &payload)?;

// Poll for durability (or use in async context)
while !handle.is_durable() {
    // Do other work...
}

// Or block if needed
handle.spin_wait();

[dependencies]
ctfs = { version = "1.0.0", features = ["persistence"] }

[dependencies]
ctfs = { version = "1.0.0", features = ["networking"] }

use ctfs::algebra::escrow::EscrowManager;

fn main() -> Result<(), ctfs::algebra::escrow::EscrowError> {
    let node_a = 1u64;
    let node_b = 2u64;

    let mut escrow = EscrowManager::new(1000); // Global limit
    escrow.initialize(&[node_a, node_b])?;     // Split 500/500

    escrow.try_consume(node_a, 400)?;          // Local op, no coordination
    escrow.transfer(node_a, node_b, 50)?;      // Quota grant
    Ok(())
}

use ctfs::core::{LatencyHistogram, MetricsServer};
use std::sync::Arc;

fn main() -> std::io::Result<()> {
    let admission_hist = Arc::new(LatencyHistogram::new());
    let persistence_hist = Arc::new(LatencyHistogram::new());

    let _server = MetricsServer::spawn(
        "0.0.0.0:9090",
        admission_hist.clone(),
        Some(persistence_hist.clone()),
    )?;

    // Record latency manually or use kernel.admit_instrumented()
    admission_hist.record(286); // 286ns latency sample
    Ok(())
}

use ctfs::core::LatencyHistogram;

fn main() {
    let hist = LatencyHistogram::new();
    hist.record(286); // Record 286ns latency

    let (p50, p90, p99) = hist.percentiles();
    let buckets = hist.snapshot(); // [u64; 64]
    println!("p50={}, p90={}, p99={}", p50, p90, p99);
}

# All benchmarks
cargo bench

# Specific suites
cargo bench --bench kernel
cargo bench --bench hardening
cargo bench --bench metrics_overhead
cargo bench --features persistence --bench durable_admission

admit_baseline           286.0 ns
admit_instrumented       298.0 ns  (+12ns overhead)
histogram_record           1.3 ns
nanos_now_rdtsc            6.6 ns
causal_clock_dominates     0.7 ns
checkpoint/tiered_hash   280.0 ns
durable_admission          5.2 ns
wal_hasher/200B          230.0 ns  (940 MiB/s)