Guarantees and limits

What each surface promises, and what your code has to do about it.

Delivery

At-least-once means a repeat is possible after a machine failure at the wrong moment. Make repeated work harmless: check an id, use INSERT OR IGNORE, or update conditionally on current state.

Stream edges narrow the window: the follower records the event in the same transaction as its handler's writes, so a redelivered event is skipped, not re-run. Effects that leave that transaction are the part to keep idempotent.

At-most-once means loss is possible. Only connection edges promise this, because a tab can vanish mid-frame. Anything that must survive belongs on the object one hop back.

Ordering

Events from one publisher reach one follower in publish order. There is no ordering promise across different publishers. If order matters across sources, put a sequence number in the data.

Calls to one object are ordered. Calls to different objects are not.

Transactions

flowchart LR
    caller([caller]) --> chain{call chain:<br/>a cycle or 32 deep?}
    chain -- refused --> caller
    chain --> mb[mailbox, 128 deep,<br/>one call at a time]
    mb --> txn[begin, method, directory row, commit]
    txn -- threw --> rollback[roll back; answer the error now]
    txn -- wrote --> ticket[take a ticket;<br/>the next call already runs]
    txn -- read only --> answer
    ticket --> flight[ship flight: frames to the replicas,<br/>then to the store]
    flight -- Q replica acks --> answer([answer released])
    flight -- no replicas: manifest written --> answer
    flight -. 10 s without either .-> unknown([outcome unknown])

A method's writes to state.sql commit together when the method returns. A state:publish inside the method is part of the same commit, so an event never describes a write that did not happen. The directory row, if the class declares one, is derived inside the same transaction.

The answer waits for one thing more than the commit: the writes leaving the machine. Calls that arrive while an answer is waiting still run, so a busy object commits at its own speed and a burst of writes leaves together. A request that makes several calls to objects on its own node gets each answer at commit and waits once, before its response and before any outbound request, for all of them.

Migrations apply inside the transaction of the call that triggered them: a failing migration applies nothing and surfaces as that call's error.

Workflow steps commit their journal entry with their result. A crash between two steps replays from the last recorded one.

Limits

Defaults, all operator-tunable on a self-hosted worker.

Guest code is metered in work rather than seconds, so waiting on io, a database or another object costs nothing and only computation counts. The clock stays as a backstop for what the meter cannot see.

The connection inbox is not a buffer to fill. A connection whose handlers cannot keep up has chosen to fall behind, and the platform severs its edges rather than growing memory on its behalf.

An idle connection hibernates: its vm drops after 300 seconds and rebuilds for the next item its program declares a handler for, with conn.state intact. A class that declared event = "forward" does not rebuild it for deliveries at all. A connection with a timer stays warm.

Failure behaviour

A hard crash cannot take back a call the platform answered. A method that wrote is not answered until its writes have reached durable storage off the machine: a quorum of the object's replica nodes, or the blob store when there are none. Nor is any other reply from that object while those writes are still in flight: a read, a method that wrote nothing, a database read served from the object's own file, all wait the same few milliseconds, so nothing outside the object ever acts on state a crash could take back. Anything you were told succeeded survives the loss of the node that ran it, and the next node to hold the object takes it over from a replica without touching the store.