How it works
An operation ledger records the boundary where an agent run changes something outside its own memory: sends an email, charges a card, opens a ticket, publishes a post, requests indexing, rotates a key, or writes to a production database. The important part is not only the final success value. It is the attempted side effect, the intent that authorized it, the target, the idempotency key or external identifier, the observed response, and the uncertainty left behind.
A useful ledger usually follows a small sequence:
- Reserve an operation identity before the external call.
- Record the proposed side effect and the authority under which it is allowed.
- Execute the call once through a controlled tool or connector.
- Store the observed result, external IDs, timestamps, and error class.
- On resume, consult the ledger before deciding whether to retry, verify, skip, or compensate.
The ledger sits beside checkpoints, traces, and result artifacts. A checkpoint says where the run was. A trace says what happened. The operation ledger says which irreversible or externally visible actions may have crossed the system boundary.
Why it matters in an agent harness
Agent runs fail in ordinary ways: process death, model stalls, browser crashes, expired credentials, ambiguous API responses, network timeouts, and operator interrupts. Without an operation ledger, a resumed run has to infer whether a side effect happened from partial context. That is a bad place to put probability. The model may be good at reconstructing intent, but intent is not evidence that the world changed.
The ledger gives the harness a deterministic place to answer operational questions. Did we already submit this URL for indexing. Did the CMS accept the publish request. Did the system send the customer message or only draft it. Did we get an unknown outcome after the request left the process. These are not writing problems. They are state problems.
This matters for control because external actions should be governed by recorded authority, not by reconstructed conversational context. A ledger entry can point to the approval, policy, credential scope, tool call, and target object that made the action legal. When those fields are missing, the harness can fail closed instead of letting a resumed agent invent a plausible explanation.
It matters for reversibility because not every operation can be rolled back directly. Some actions require compensation: delete the created draft, void the transaction, post a correction, notify a human, or mark a workflow as needing manual repair. Compensation only works when the original operation is named clearly enough to undo or neutralize. A vague trace line is not enough.
It also matters for observability. Production operators need to know whether a failure is content-level noise, model indecision, tool flakiness, or a real unknown side effect. The ledger makes that distinction visible. A timeout after a request was sent should not be treated like a validation error before the request was attempted. Those two failures call for different recovery behavior.
Operation ledger vs execution journal
The distinction changes how we design recovery. An execution journal can describe the run broadly. An operation ledger is narrower and stricter: it tracks side effects that may matter outside the process.
| Concept | Primary question | Typical contents | Recovery role |
|---|---|---|---|
| Operation ledger | Did this external action occur or become ambiguous. | Operation key, target, authority, request, response, external ID, outcome class. | Prevents duplicate side effects and drives verify, retry, skip, or compensate decisions. |
| Execution journal | What did the run do over time. | Steps, tool calls, logs, intermediate outputs, model decisions. | Supports debugging, audit, replay, and evaluation of the trajectory. |
The two should reference each other. The journal helps explain how the system reached a decision. The ledger is the harder boundary for production recovery. If storage pressure forces a choice, preserve the ledger fields needed to avoid duplicate or unauthorized action.
The Rifty take
We treat operation ledgers as part of the control surface, not as optional logging. A harness that can resume work but cannot remember its side effects is only partially durable. We accept some extra bookkeeping because it buys a cleaner boundary: the model may propose a retry, but the harness decides whether retrying is safe.
Implementation checks
- Use stable operation keys derived from the business object and intended side effect, not from a transient model message.
- Record intent before the external call, then update the entry after the observed result.
- Separate
succeeded,failed_before_send,failed_after_send, andunknown_outcome; do not collapse them into a generic error. - Store external IDs, request IDs, URLs, resource versions, and timestamps when the provider returns them.
- Make retries consult the ledger before touching the external system again.
- Treat missing ledger state for a high-impact side effect as a recovery problem, not a reason to repeat the action.
- Attach authority: approval record, policy decision, credential scope, or delegated permission.
- Design compensating actions from ledger fields, then test them with fault injection around timeouts and process death.
- Keep ledger writes durable enough to survive the same failures that trigger resume.
- Expose ledger state to operators in plain outcome categories, especially for unknown outcomes.
Frequently asked questions
Is an operation ledger just an audit log?
No. An audit log explains what happened for later inspection, while an operation ledger participates in recovery decisions. It must be queryable by operation identity during resume so the harness can decide whether to retry, verify, skip, or compensate an external side effect.
What should be recorded before the external call?
Record the operation identity, intended side effect, target object, authorized actor or policy, credential scope, and enough request shape to recognize the same action later. This pre-call record matters because the process can fail after sending the request but before receiving or storing the response.
How does an operation ledger relate to idempotency?
An operation ledger complements idempotency but does not replace it. Idempotency keys ask the external system to collapse duplicates. The ledger lets the harness remember which key was used, what response was observed, and whether the next safe action is retry, verification, or compensation.
What is the hardest state to handle?
The hardest state is unknown outcome: the request may have reached the external system, but the harness did not receive durable confirmation. Treating that as a simple failure creates duplicate-action risk. A good harness verifies externally or escalates according to the operation's blast radius.
When is a lightweight ledger enough?
A lightweight ledger is enough when the side effect is low impact, naturally idempotent, and easy to inspect after the fact. Higher-impact actions need stronger fields: stable keys, authority references, external IDs, outcome classes, and compensating-action data. The control should match the consequence.