State management for Common Agent Runtime.

Provides structured, typed state with transition logging. Every mutation produces a StateTransition record for audit and replay.

Persistence (Parslee-ai/car#181)

StateStore::durable(path) opens a JSONL-backed store. Each mutation appends a transition line; on construction the file is replayed to rebuild current state. This is the agent-persistence pattern documented in docs/persistence.md. JSONL was chosen over sqlite/sled to stay aligned with the existing JSONL persistence used by car-eventlog and car-memgine — one file shape, one reap+compact story, no native build deps.

Per-key TTL is supported via set_with_ttl — the in-memory state drops the key when reap_expired(now) runs after the deadline. The on-disk file is compacted at the same time so the journal doesn't grow unbounded.

car-state

Thread-safe state store for the Common Agent Runtime.

What it does

A key-value state store where every mutation produces a StateTransition record for audit and replay. Supports snapshots and restore for rollback. Uses parking_lot::Mutex for low-overhead concurrent access.

Usage

use car_state::StateStore;
use serde_json::Value;

let store = StateStore::new();
store.set("auth", Value::Bool(true), "action-1");
assert_eq!(store.get("auth"), Some(Value::Bool(true)));

let snap = store.snapshot();
store.set("temp", Value::from(42), "action-2");
store.restore(snap, 1); // rollback

Part of CAR -- see the main repo for full documentation.