One tap, followed message by message, with the real data. The example is the todo app from How it works: completing a todo ticks it and gives 10 XP.
The library defines two pieces of data: the rules (message 1) and the answer's list (message 4). How they travel is your app's choice. Here they travel as JSON over HTTP, and notifications over a WebSocket.
1. App start: the server sends the rules
The :rules action of AshBackendDrivenOptimisticUi.RuleSet returns:
{
"version": "5c1e09ab77d3f240",
"rules": {
"todo.complete": {
"effects": [
{
"where": {"!": [{"var": "record.done"}]},
"effects": [
{"set": {"done": true}, "source": "declared"},
{"push": {"event": "xp_awarded", "payload": {
"amount": 10,
"id": {"var": "ctx.push_ids.xp_awarded.complete"}
}}}
]
}
],
"reactions": [
{"on": "xp_awarded", "type": "user_level", "effects": [
{"set": {"total_xp": {"+": [{"var": "record.total_xp"}, {"var": "event.amount"}]}},
"source": "declared"}
]}
]
}
}
}The app keeps this until version changes.
2. What the app holds before the tap
The todo, as the server sent it earlier. ctx came with it:
{
"id": "42",
"title": "Buy milk",
"done": false,
"updated_at": "2026-10-25T18:03:00.123456Z",
"ctx": {
"push_ids": {
"xp_awarded": {
"complete": "todo:42:2026-10-25T18:03:00.123456Z:xp_awarded:complete"
}
}
}
}The user's level:
{"id": "7", "total_xp": 120}3. The tap
Nothing is sent yet. The app runs todo.complete on what it holds.
The where is true (done is false), so:
the
setgives the todo"done": true;the
pushbecomes this event, which the app shows as a toast:{ "event": "xp_awarded", "payload": { "amount": 10, "id": "todo:42:2026-10-25T18:03:00.123456Z:xp_awarded:complete" } }the reaction gives the level
"total_xp": 130.
The app remembers the id it showed.
4. The save and its answer
The request is your normal one, plus the ids the app showed:
PATCH /todos/42/complete
x-optimistic-ids: todo:42:2026-10-25T18:03:00.123456Z:xp_awarded:completeThe server runs the action. Before the action it called
PushCollector.open(), and after it
PushCollector.drain_reconciliation(ids), which returns:
{
"pushes": [
{
"event": "xp_awarded",
"payload": {
"amount": 10,
"id": "todo:42:2026-10-25T18:03:00.123456Z:xp_awarded:complete"
}
}
],
"retracted": []
}Your app puts that in the answer. Over HTTP, under meta:
{
"data": {"id": "42", "title": "Buy milk", "done": true},
"meta": {
"pushes": [
{
"event": "xp_awarded",
"payload": {
"amount": 10,
"id": "todo:42:2026-10-25T18:03:00.123456Z:xp_awarded:complete"
}
}
],
"retracted": []
}
}The app reads it:
pusheshas the id it already showed, so it shows nothing again.retractedis empty, so the guess stands.
5. The notifications
The server's notifiers send the same things over the WebSocket, as they did before this library existed. The event:
{
"event": "xp_awarded",
"payload": {
"amount": 10,
"id": "todo:42:2026-10-25T18:03:00.123456Z:xp_awarded:complete"
}
}Same id, so the app skips it. And the real records, which replace the guesses:
{"id": "42", "title": "Buy milk", "done": true, "updated_at": "2026-10-25T18:03:02.456789Z"}{"id": "7", "total_xp": 130}The guess was right, so nothing on screen changes. The todo's
updated_at moved, so the next tap gets a new id.
When the guess was wrong
The save worked, but the server gave no XP. The answer:
{
"data": {"id": "42", "title": "Buy milk", "done": true},
"meta": {
"pushes": [],
"retracted": ["todo:42:2026-10-25T18:03:00.123456Z:xp_awarded:complete"]
}
}retracted names the event the app showed and the server did not send.
The app puts back what it held before the tap (total_xp is 120 again),
and the real todo arrives by notification with "done": true.
When the save fails
The server answers with its usual error and no list:
{"errors": [{"detail": "is already done"}]}The app puts back what it held before the tap.
When nothing was guessed
No ids sent and nothing pushed: drain_reconciliation/1 returns nil,
and the answer is exactly what it was without this library.