Core Concepts
State slots
An object's state is a flat map of named slots. Each slot holds any JSON-serialisable value.
{
"status": "processing",
"assigned_to": "agent-7",
"retry_count": 2,
"history": [{ "event": "created", "at": 1718884800000 }]
}Slots are created on first write and deleted explicitly. No schema required.
The append-only log
Every write appends an immutable entry:
log_id is monotonically increasing, unique per object, returned on every write and included in every change event. State is rebuilt by replaying the log on restart — no data loss possible.
Operations
| Operation | Description | Returns |
|---|---|---|
set(slot, value) | Set a single slot | { log_id } |
setAll(map) | Set multiple slots atomically | { log_id } |
get(slot) | Read a single slot | { value } |
increment(slot, by?) | Atomic integer increment (by defaults to 1) | { log_id, value } |
append(slot, value) | Append to a list slot | { log_id } |
delete(slot) | Remove a slot | { log_id } |
transaction(ops) | Atomic multi-write (an array of ops — no reads) | { log_id } |
state() | Read full state map + log_id | { …state, log_id } |
log(after?) | Replay log entries after a position | { items: [...] } |
purge() | Delete all state and log | 204 |
Object lifecycle
Objects spring into existence on first write. There is no explicit create. purge() permanently deletes all state and log entries.
Real-time subscriptions
Every subscriber receives changes in log order. afterLogId replays only missed entries — efficient RocksDB prefix scan, not a full scan.
Transactions
A transaction is a list of write operations (set, delete, increment,
append) that commit together in one log entry, or not at all. It is
serialised server-side — no two writes to the same object run concurrently.
The HTTP and SDK transaction is write-only — there is no read operation
inside it. For a conditional write, read the object first (get / state),
decide, then send the transaction. Because writes are linearised, the only race
is the brief window between your read and your write.
Consistency guarantees
- Within one object: all writes are linearised.
incrementandtransactionare always atomic. - Across objects: no cross-object transactions. Use an orchestrating process that writes sequentially.
- Subscribers:
change/batchevents are delivered in log order — a subscriber never seeslog_idN+1 before N. - Replication: objects are replicated across the cluster with an adaptive
quorum —
N=1on a single node,N=2with two nodes,N=3with three or more (R=W=2). See Architecture.