CrabTalk Start
Blog

Storage commits when the tool call succeeds

A tool reads its own pending writes. Failed calls discard them. The transaction covers the service’s storage, with a clear boundary around external actions.

CrabTalk Team

A website watcher keeps two things in storage: the changes it has found and a checkpoint recording how far it has read. One tool call adds a change and advances the checkpoint from 104 to 105.

If the call fails between those writes, storing them independently would leave the watcher’s state out of step. A retry could encounter a change without its checkpoint, or skip a change whose checkpoint was saved first.

On CrabTalk, the tool call is the commit boundary for its storage changes. The watcher can make both writes, read them while it works, and return success when it has finished. A failed call discards its pending changes.

The writes commit together

For the watcher, the outcomes are:

Outcome Change 105 in storage Stored checkpoint
Before the call Absent 104
Call succeeds Present 105
Call fails Absent 104

Storage changes commit only when the tool call succeeds with Ok. Returning Err, trapping or exceeding the deadline discards the call’s pending changes.

When a service declares SQL storage, its SQL statements and values by key share one transaction. The watcher can keep its change history in a table and its checkpoint under a key without creating separate commit boundaries. Services using only values by key follow the same read and commit rules.

The host manages the transaction. Service code does not issue BEGIN or COMMIT; transaction-control statements are refused.

Read your writes during the call

Deferring the commit still lets the tool use the state it has just written. Inside a writing tool, this fragment stages a checkpoint and reads it back:

berm_lang::set_json("last_seen", &105_u64)?;
let last_seen: Option<u64> = berm_lang::get_json("last_seen")?;

last_seen is Some(105), even though the tool has not returned yet. Later steps in the same call can use that value. SQL reads likewise see earlier SQL writes in the call.

Independent calls cannot read those pending changes. While the watcher’s update is uncommitted, an independent read sees the previously committed checkpoint, 104. If the watcher fails, 105 never becomes committed state.

This is also what “rollback” means here: abandoning uncommitted changes. It does not mean publishing 105 for other callers and then changing it back after an error.

The final result matters

An error handled inside the tool is different from a tool returning an error. If the tool catches an operation’s error, continues and returns Ok, it has chosen a successful outcome; its pending storage changes can commit.

If completing the watcher requires both the history write and the checkpoint update, propagate an error from either operation. Returning Err preserves the previous committed state.

External actions have their own outcome

The transaction covers the service’s own storage. An HTTP action is outside it. If a tool sends a notification and then fails, discarding its storage changes cannot unsend the notification. Retrying that tool can send it again unless the receiving system supports deduplication, such as an idempotency key.

The same boundary matters when calling another service. If that service has already committed a change, a later failure in the caller does not undo it. A chain of service calls is not one transaction spanning all their storage.

The watcher can therefore keep its own history and checkpoint consistent across a failed call. Delivering notifications exactly once is a separate problem.

We clarified these existing semantics in the storage documentation and the transaction example on the Services page. The essential contract is explicit: a call sees its pending writes, independent calls cannot see them, and storage changes commit only when the call succeeds.