iii-state

The iii-state worker is a server-side key/value store. Values are addressed by a scope (namespace) and a key, shared across every worker connected to the engine, and persisted through a pluggable adapter (kv, redis, or bridge). Callers reach the store through six state::* functions invoked with iii.trigger({ function_id: 'state::...', payload }).

State does not push updates to SDK clients. Reactivity is delivered by a state trigger type that fires state:created, state:updated, or state:deleted after every successful mutation, so downstream functions can react to data changes without polling. The kv adapter (default) supports in_memory or file_based persistence; redis proxies to a Redis backend; bridge forwards operations to a remote iii engine. The function surface is identical across adapters.

When to Use

Two or more functions need shared state without standing up a separate database.
A counter or per-entity document needs atomic partial updates instead of read-modify-write.
A write in one function should trigger side effects elsewhere (cache invalidation, audit logs, notifications, projections).
You want a specific scope/key watched and reacted to only when that slot changes.

Boundaries

Schema-free by design — every value is opaque JSON. Use configuration when entries need a registered JSON Schema and validation.
Reads (state::get, state::list, state::list_groups) never fire triggers; only set/update/delete do.
Trigger delivery is asynchronous and does not roll back the write on handler failure; a delete of a missing key still emits state:deleted with a null old value.
Stream-shaped, broadcast-to-subscribers data belongs in iii-stream, not here.