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

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. 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.

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.

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.

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.

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 and 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 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, the core uses the contract types to request cached data:

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 fulfills the contract:

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 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}