How to Migrate from Audit Logs to Verifiable Receipts

Last updated: 2026-09-28

Do not replace audit logs with receipts wholesale. Keep logs for diagnosis and add verifiable receipts at the boundaries where a reviewer needs proof that a specific action ran and what the execution layer observed.

Try the Zambo demo · Explore Zambo

Use the public receipt verifier to inspect a receipt when you have one. A receipt is evidence about a recorded execution, not a guarantee that an outside system accepted the result or that a human decision was correct.

Logs and receipts have different jobs

Audit logs are broad operational records. They help operators search a run, inspect retries, follow stack traces, and understand system behavior. A verifiable receipt is a focused evidence object for a specific execution claim. It gives a reviewer a stable reference, selected fields, canonical bytes, and an integrity check. Logs answer how the system behaved in detail. Receipts answer what record supports this particular claim. A migration fails when a team deletes useful diagnostic context or expects a compact receipt to reconstruct every internal event.

Choose the first claim

Begin with a claim that matters and has a clear execution boundary. Examples include a tool call that changed a record, a deployment operation, a message send request, or a model-assisted approval step. Write the claim in one sentence and list what would count as independent support. If the claim includes an outside effect, split it into execution and outcome claims. The receipt can cover the former and perhaps an explicitly observed portion of the latter. This step prevents a vague project from producing a large number of records with no review purpose.

Inventory the current log path

Document where the event starts, which services transform it, where retries occur, and which system owns the final state. Identify the existing request id, trace id, actor scope, timestamp source, and retention policy. Mark fields that contain secrets or personal data. Then decide which receipt fields can be populated from facts already present and which require a new observation. Do not infer a tool result from a planned command. A migration is safer when it makes uncertainty visible before adding a new format.

Phase one: dual write

For a limited flow, keep the existing log and create a receipt at the chosen boundary. Store the receipt id in the log context and store the log or trace reference alongside the receipt metadata where allowed. Compare counts and failure modes for a defined period. If receipt creation fails, do not block the business action unless the risk owner explicitly chooses fail-closed behavior. Instead, emit a collection failure that can be measured. Dual writing gives the team time to learn without pretending the new path is complete.

Phase two: reviewer workflow

A format becomes useful when a person or service can use it. Build a small review procedure: resolve the receipt, check the identifier and timestamp, inspect tool and scope, verify canonical bytes and output hash, and compare the result with the owning system. Link the procedure to /verify when the record is public. Train reviewers to record three outcomes: evidence supports the narrow claim, evidence is partial, or evidence is unavailable. Avoid a single green status that hides the difference between integrity and correctness.

Phase three: incident integration

Add receipt references to incident timelines, change reviews, and handoff templates. Keep detailed logs linked for diagnosis. When an incident involves an agent, compare the agent summary with the receipt set and identify claims with no matching execution. Preserve failed and partial receipts. A later successful retry does not erase the earlier failure. This structure shortens review because the responder can start with material actions, then open logs only when more context is needed.

What receipts replace

Receipts can replace informal assertions such as a chat message saying that a tool ran, a manually copied success line, or an unscoped screenshot used as proof. They can also replace brittle summaries as the primary reference for one execution. They do not replace logs, traces, source control history, approvals, configuration snapshots, access records, monitoring, or system-of-record checks. The migration should explicitly list what remains in each system. Otherwise teams will delete the evidence that explains why the receipt looks the way it does.

Data contracts and failure modes

Define required fields, serialization rules, timestamp requirements, hash behavior, and unsupported versions. Test malformed identifiers, missing fields, invalid timestamps, changed bytes, and missing records. Decide how a transport failure is reported and retried. A verifier should distinguish an invalid receipt from an unavailable page. Do not silently accept a truncated response or reserialize bytes under a different canonicalization. These details are operational safeguards, not decorative schema work.

Measuring the migration

Track receipt coverage for the chosen claim, creation failures, verification failures, missing outcome checks, unmatched log references, and reviewer time. Coverage should be based on the population that should have produced a receipt, not only on records that exist. Sample receipts against the owning system. If a metric improves because the system stopped recording failures, it is not an improvement. Keep the measurement definitions beside the rollout plan so a later team can reproduce the baseline.

When to stop or roll back

Pause the rollout if the receipt fields encourage unsupported claims, if privacy exposure increases, if verification is too slow for the incident path, or if receipt creation changes the action's semantics. Keep the dual-write path until the replacement has a documented owner and recovery procedure. A staged migration is successful when reviewers can distinguish recorded execution, outside outcome, and missing evidence. The point is not to call every log a receipt. It is to make important claims easier to check without losing operational truth.