# Tinyjuice-Bus Contract CCR Caching: OpenHuman's Cross-Module Token Cache Protocol

> Explore the tinyjuice-bus contract for CCR caching. Discover how OpenHuman's protocol enables efficient token caching for serialized AST data with TTL expiration and type-safe RPC.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: internals
- Published: 2026-08-30

---

**The tinyjuice-bus contract defines a `#[repr(C)]` CCR (Chunk-Cache-Retrieval) interface with `CcrCacheKey` and `CcrCacheEntry` structs, enabling type-safe RPC between the OpenHuman core and tokenjuice inference modules for caching serialized AST data with configurable TTL expiration.**

The `tinyjuice-bus` crate serves as the canonical contract layer between the OpenHuman inference engine and its tokenjuice parsing modules. By standardizing CCR caching definitions in this shared crate—located under `vendor/tinyjuice/crates/tinyjuice-bus`—the system ensures that expensive tokenization results can be cached and reused across process boundaries without duplicating logic or data structures.

## Core CCR Data Structures in the Contract

The CCR caching contract specifies three primary types in [`vendor/tinyjuice/crates/tinyjuice-bus/src/types.rs`](https://github.com/tinyhumansai/openhuman/blob/main/vendor/tinyjuice/crates/tinyjuice-bus/src/types.rs). All types carry `#[repr(C)]` and implement `serde::Serialize` and `Deserialize` to guarantee ABI stability across the wire.

### CcrCacheKey

The `CcrCacheKey` struct wraps a deterministic string identifier—typically a SHA-256 hash of the source text combined with parser options.

```rust
pub struct CcrCacheKey(pub String);

```

### CcrCacheEntry

The `CcrCacheEntry` struct stores the actual cached payload alongside metadata for expiration. The `ttl` field represents the time-to-live in seconds.

```rust
pub struct CcrCacheEntry {
    pub key: CcrCacheKey,
    pub value: Vec<u8>,
    pub ttl: u64,
}

```

### CacheError

The `CacheError` enum defines failure modes that the module can return to the core, forcing explicit error handling rather than silent failures.

```rust
pub enum CacheError {
    Full,
    Corrupt,
    InvalidKey,
}

```

## RPC Interface Methods

The contract exposes three RPC-style methods that the OpenHuman core invokes against the tokenjuice module. These are defined in [`vendor/tinyjuice/crates/tinyjuice-bus/src/lib.rs`](https://github.com/tinyhumansai/openhuman/blob/main/vendor/tinyjuice/crates/tinyjuice-bus/src/lib.rs).

### CcrCacheGet

**`fn get(key: CcrCacheKey) -> Option<CcrCacheEntry>`** retrieves a cached entry by key. The implementation returns `None` if the key is absent or the TTL has expired.

### CcrCacheSet

**`fn set(entry: CcrCacheEntry) -> Result<(), CacheError>`** persists a new cache entry. The module validates the entry and may return `CacheError::Full` if storage quotas are exceeded or `CacheError::InvalidKey` if the key format violates constraints.

### CcrCacheClear

**`fn clear() -> Result<(), CacheError>`** provides a nuclear option for cache eviction, invoked during shutdown or when the user explicitly requests a cache reset via the OpenHuman CLI.

## Implementation Flow in OpenHuman

The CCR caching lifecycle operates across four distinct phases, coordinating between [`src/openhuman/inference/tokenjuice/types.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/inference/tokenjuice/types.rs) and [`src/openhuman/modules/tokenjuice_host.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/tokenjuice_host.rs).

1. **Key Generation**: When the inference engine receives text to parse, it normalizes the input and constructs a `CcrCacheKey` from the normalized source hash.

2. **Cache Lookup**: The engine calls `CcrCacheGet`. If the call returns `Some(entry)`, the core deserializes the `Vec<u8>` payload directly into an AST, bypassing the parser entirely.

3. **Computation and Insert**: On cache miss, the engine performs the full token-juice parse, serializes the resulting AST to bytes, builds a `CcrCacheEntry` with a typical TTL of 300 seconds (5 minutes), and invokes `CcrCacheSet`.

4. **Expiration and Eviction**: The module-side implementation in [`tokenjuice_host.rs`](https://github.com/tinyhumansai/openhuman/blob/main/tokenjuice_host.rs) monitors the `ttl` field; entries exceeding their TTL are treated as absent on subsequent lookups. The core may also trigger `CcrCacheClear` during module reloads.

## Code Examples

### Core Side Cache Retrieval

Located in [`src/openhuman/inference/tokenjuice/types.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/inference/tokenjuice/types.rs), the core uses the contract types to request cached data:

```rust
use tinyjuice_bus::{
    CcrCacheKey, CcrCacheEntry, CcrCacheGet, CcrCacheSet,
};

fn get_cached_ast(source: &str) -> Option<Vec<u8>> {
    let key = CcrCacheKey(source.to_string());
    match CcrCacheGet::call(key) {
        Ok(Some(entry)) => Some(entry.value),
        _ => None,
    }
}

fn store_ast(source: &str, serialized_ast: Vec<u8>) {
    let entry = CcrCacheEntry {
        key: CcrCacheKey(source.to_string()),
        value: serialized_ast,
        ttl: 300, // 5 minutes
    };
    let _ = CcrCacheSet::call(entry);
}

```

### Module Side Implementation

The host implementation in [`src/openhuman/modules/tokenjuice_host.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/tokenjuice_host.rs) fulfills the contract:

```rust
use tinyjuice_bus::{
    CcrCacheKey, CcrCacheEntry, CacheError,
    CcrCacheGet, CcrCacheSet,
};

fn handle_get(key: CcrCacheKey) -> Option<CcrCacheEntry> {
    // Implementation-specific LRU cache lookup
    MY_LRU_CACHE.get(&key.0).cloned()
}

fn handle_set(entry: CcrCacheEntry) -> Result<(), CacheError> {
    if entry.value.is_empty() {
        return Err(CacheError::InvalidKey);
    }
    if MY_LRU_CACHE.len() >= MAX_ENTRIES {
        return Err(CacheError::Full);
    }
    MY_LRU_CACHE.put(entry.key.0, entry);
    Ok(())
}

```

## Summary

- The **tinyjuice-bus contract** defines `CcrCacheKey`, `CcrCacheEntry`, and `CacheError` in [`vendor/tinyjuice/crates/tinyjuice-bus/src/types.rs`](https://github.com/tinyhumansai/openhuman/blob/main/vendor/tinyjuice/crates/tinyjuice-bus/src/types.rs) to ensure binary-compatible caching across process boundaries.
- **RPC methods** `CcrCacheGet`, `CcrCacheSet`, and `CcrCacheClear` specify the exact interface for cache operations, returning `Option` and `Result` types that force explicit error handling.
- **TTL-based expiration** is encoded directly in the `CcrCacheEntry` struct, allowing module implementations to evict stale entries without core coordination.
- **Source file separation** between `src/openhuman/inference/tokenjuice/` (core consumer) and [`src/openhuman/modules/tokenjuice_host.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/tokenjuice_host.rs) (module implementer) demonstrates strict adherence to the contract boundary.

## Frequently Asked Questions

### What does CCR stand for in the tinyjuice-bus contract?

CCR stands for **Chunk-Cache-Retrieval**. It refers to the mechanism by which the OpenHuman core stores and retrieves serialized chunks of parsed token-juice AST data to avoid redundant computation across inference calls.

### How does the contract handle cache expiration?

The `CcrCacheEntry` struct includes a `ttl: u64` field representing seconds until expiration. Module implementations in [`tokenjuice_host.rs`](https://github.com/tinyhumansai/openhuman/blob/main/tokenjuice_host.rs) inspect this field during `CcrCacheGet` calls and return `None` if the current time exceeds the entry's creation time plus TTL, effectively treating expired entries as cache misses.

### What happens when the cache returns an error?

When `CcrCacheSet` returns `Err(CacheError)`, the OpenHuman core falls back to immediate recomputation of the token-juice parse. The `CacheError` enum variants (`Full`, `Corrupt`, `InvalidKey`) allow the core to log specific diagnostics—for example, distinguishing between a temporarily full cache requiring eviction versus a corrupted entry indicating data integrity issues.

### Why are the CCR types marked with #[repr(C)]?

The `#[repr(C)]` attribute guarantees a stable, platform-independent memory layout for `CcrCacheKey` and `CcrCacheEntry`. This ensures that the OpenHuman core (potentially compiled with different settings or versions) and the tokenjuice module can pass these structs across the TinyBus wire protocol without ABI mismatches, while `serde` handles the actual byte-level serialization for network transmission.