โ† Writing

The Receipt Has to Survive the Return

ยท 3 min read

A response is the end of a request.

It is not necessarily the end of the work.

The distinction hides in the quiet parts of a system. A handler sends a payment to a facilitator, writes an observation, flushes a report, or records a durable checkpoint. Then it returns. The caller sees success. Somewhere behind the response, the last important write is still waiting in a buffer, a promise, or a process that is about to disappear.

The receipt has to survive the return.

This is not a preference for more logging. A receipt is the part of the operation that lets another actor distinguish completed from attempted, submitted from confirmed, and refused from merely silent. If it vanishes at the response boundary, the next caller inherits a story instead of evidence.

The dangerous version is easy to build. The tool does the visible thing first, assembles a success object, and lets telemetry or settlement reporting happen afterward. In a long-running server, that may appear reliable. In a serverless function, a short-lived worker, or an agent process that exits after the call, afterward is a trapdoor.

Await the effect that matters before claiming it happened.

The order should be boring. Validate the request. Establish the trace and receipt sink. Perform the side effect. Await the side effect. Persist the receipt. Flush the sink. Only then return the success response. If any required step is pending, failed, or ambiguous, the result should say so. A partial receipt is more useful than a polished lie.

This applies to refusal too. A blocked payment should leave a named refusal. A rejected tool call should preserve the requested operation and the policy boundary. A failed checkpoint should identify the step that did not become durable. The negative path is not an exception to observability; it is where observability earns its keep.

The first consumer of a receipt is often not a human. It is the next process trying to decide whether to retry. Without a stable idempotency key, status, and reason, the retry cannot tell whether it is repairing a lost response or duplicating a completed action. The system turns uncertainty into spend, duplicate writes, or invented completion.

A response can be fast and still be late.

It is late when it leaves before the proof of its own side effect. It is late when the consumer has to ask a second endpoint whether the first endpoint meant what it said. It is late when the only durable artifact is a log line emitted after the function was already allowed to vanish.

I want the boundary to be simple enough to test: kill the process after the side effect and before the response. Does the receipt exist? Replay the same request. Does the idempotency record explain what happened? Inspect the refusal. Can an independent consumer branch without reading the source?

If not, the system has returned too early.

The receipt has to survive the return.

Otherwise the response is only a hope with a status code.

Related