Concepts
Ledger and marks
The ledger is the record of everything that happens in Kelvar. A mark is a fact that the ledger only records after a deterministic check has passed. Together they are why you can trust a result without trusting the model that produced it.
#The ledger
Every time something crosses a boundary, Kelvar writes one row. The file is ledger/movements.jsonl inside your Home. It is append-only, and a SQLite index on top of it makes it fast to query.
A row records what arrived, where it went and why. That covers the following.
- Messages you send and replies you receive.
- Tool calls an agent makes, and their results.
- Findings an agent records.
- Refusals. A request outside an agent's grant is recorded as a
DeliveryRefusedrow with its reason. - Failed verifications. A check that did not pass is a row too.
Nothing is dropped silently. If something did not happen, the ledger says why.
#Replay
Because every step is recorded, a run can be replayed. The runtime reads its state from the ledger rather than from memory, so an interface that restarts catches up from its own cursor and continues. A replay shows the same sequence of movements, though it cannot make a model provider's reply or an external effect repeat identically.
#Marks
A mark is the recorded fact that a verifier passed over an artifact. The runtime writes it. A model never does.
For example, when an agent writes a file, a verifier checks that the target file now matches what the agent said it wrote. Only if that passes does the ledger record the mark. If the verifier fails, the failure is recorded and the agent's claim stays a claim.
| Verifier | What it checks |
|---|---|
file_write_target_matches | The file on disk matches the content the agent wrote. |
authoring_apply_succeeded | A change to the registry, such as a new agent or room, was applied. |
A checkpoint can require a verified artifact before it closes. This is how Kelvar holds a step until its proof exists.
#What a mark does not prove
A mark proves that its verifier passed over its evidence. "The file matches" is a real check. "The agent stayed on-contract and wrote nothing harmful" is not a check that exists today. Treat marks as a precise statement about one fact, not as a proof of safety.
#Using the ledger
The ledger is your audit trail. You can use it to answer questions such as the following.
- What did this agent read, and when?
- Which requests were refused, and for what reason?
- Which verifier confirmed this change?
- Which run produced this finding?
Billing uses the same record. Each charge on a usage invoice maps to a completed run in your ledger, so you can replay what you were billed for. See Pricing and billing.