Behaviour — the flows that can go wrong

Not the most important flows and certainly not all of them. Pick the ones that cross a boundary, write in two places, touch money or personal data, or hold a user waiting on something you do not control. Four or five. A runtime view with fourteen flows is a re-description of the application and will be abandoned within two quarters.

The selection test is a single question: if this flow silently half-completes, who finds out, and how? If the answer is a customer, next month, by email, that flow belongs on the page regardless of how simple it looks.

The flows that fail this test are worth skipping deliberately. A read that hits one store and returns is not architecture, no matter how central it is to the product — it is code, and the code is clearer than any diagram of it.

The happy path exists to orient a reader, not to inform them. Three numbered lines: what is received, what is written, what is emitted. Anything longer duplicates the implementation, ages with every refactor, and pushes the useful part below where people stop reading.

Then the four bullets that justify the page: partial failure, retry and idempotency, what the user sees while degraded, and the consistency actually guaranteed. Every one of them is a decision someone will otherwise make silently, at 2am, under pressure, in one call site.

Written this way a flow entry fits on half a page. That is the length at which it gets updated when the flow changes, which is the only property of documentation that ultimately matters.

Step three wrote to the database, step four called the provider and timed out. Where does the system now sit, is that state detectable, who or what resolves it, and how long is it allowed to sit there? Four questions, and a design that cannot answer them has not been finished — it has been started and deployed.

Name the mechanism rather than the intention. Compensating action, outbox with reconciliation, a scheduled sweep of records older than an hour, or an accepted inconsistency with a stated window. "Accepted, reconciled nightly, worst case 24 hours stale" is a legitimate answer and a good one; "we handle errors" is not an answer at all.

The failure path also needs an owner and a signal. An inconsistency that nothing alerts on is an inconsistency you will hear about from a customer, and by then the record is weeks old and the reconciliation is manual.

"We use a relational database, so we are consistent" stops being true the moment a cache, a read replica, a queue, a search index or a second service enters the flow — which is to say, immediately. Transactions guarantee something about one store; the flow crosses several.

So state it per flow and in the vocabulary that has meaning: read-your-writes for the user who just submitted, monotonic reads inside a session, eventual with a bounded lag for everyone else. Then say what the bound is, because an eventual guarantee with no stated lag is not a guarantee, it is a hope with a technical name.

This is the bullet where designs are most often quietly wrong, and the error is nearly always the same shape: a write goes to the primary, the next read goes to a replica, and the user sees their own change missing. It is obvious once written down and invisible in a sequence diagram.

A trace is a sequence diagram that cannot be out of date, and any competent observability stack produces one per request. Stop drawing the picture; link to an exemplar trace and spend the effort on semantics.

What a trace cannot express is intent: which of those calls was allowed to fail, which retry was safe, what the system should have done when the fourth span timed out. A trace of a broken flow tells you what happened, not whether it was correct, and those are different questions with different owners.

Three layers each retrying three times is twenty-seven requests to a service that is already struggling, arriving in a synchronised wave the moment it starts recovering. The retry is the amplifier, and every incident review that mentions a thundering herd is describing a policy nobody wrote down.

The current default worth stating per flow: exponential backoff with jitter, a budget for the whole request rather than a count per hop, and a circuit breaker on anything on a user-facing path. The budget is the part that gets skipped and the part that matters — retries that outlive the caller's deadline are pure load with no possible benefit to anyone.

And retry only what is idempotent. A retried non-idempotent write is a duplicate charge, a duplicate email, a double shipment. The rule is not that retries are dangerous; it is that a retry policy without an idempotency story is a duplicate-generation policy.

Exactly-once delivery does not exist across a network. Effectively-once does, and it is built the same way everywhere: at-least-once delivery plus a deduplication key with a retention window, or a transactional outbox so the write and the intent to publish commit together.

Three fields decide whether it works, so write them down per flow. Where the key comes from — client-generated, the order id, a natural key — how long the dedup record is kept, and what the system does when the same key arrives with a different payload. That third case is where the subtle bug lives: silently returning the first result is right for a retried payment and wrong for an edited one, and only the flow's author knows which.

A queue gives you ordering per partition, not globally, and redelivery is a feature rather than an anomaly. Both facts belong in the flow entry, because a consumer written on the assumption of global order works fine in test and reorders in production under load.

The dead-letter queue needs an owner in the same way a block needs one. A DLQ nobody reads is a data-loss mechanism with a reassuring name — the messages are safe, nothing is fixed, and the discovery is usually a customer report.

Asynchrony also makes intermediate states user-visible, which turns them into design decisions. "Pending" is not an implementation detail: someone has to decide what it looks like, how long it is acceptable, whether the user can act during it, and what happens if it never resolves. Deciding that in the flow document costs a paragraph; deciding it in the UI costs a support queue.

The recurring shapes are predictable enough to enumerate: a retry loop wrapped around a non-idempotent write, an exception swallowed so the flow continues with an empty result, an unbounded backoff on a request a person is waiting for, a timeout treated as a failure when the write actually succeeded.

Each is a reasonable guess in the absence of a stated policy, and each has a postmortem attached to it in someone's incident tracker. The problem is not that the model is careless; it is that the information required to be careful — is this write idempotent, what is the deadline, who reconciles — exists nowhere in the code it was given.

Review does not catch these reliably either, because the failure branch is the part of a diff that reads as boilerplate. It is caught by a stated policy and a test that injects the failure, or it is caught in production.

These are facts about the business and the infrastructure, not properties recoverable from source. Whether a duplicate charge is catastrophic or merely embarrassing, how long a user will wait, whether events for one customer must be processed in order — no amount of reading the code answers any of them.

Which is why the flow document is the highest-value page in the spine for generated integration code, despite having no machine layer of its own. Four bullets per flow, in the repository, is the difference between an agent implementing your failure policy and inventing one.

The practical form is a short table per flow: step, retryable, idempotency key, deadline. It is compact enough to sit in a session prompt, specific enough to remove the guesses, and it is the page an agent should be required to cite when it writes a client for a flow that appears on it.

Bind each failure bullet to something that runs: a fault-injection test that kills the process between two writes, a contract test that returns a 500 and a timeout, a consumer test that redelivers a message it has already handled. This is the guardrails concern applied to behaviour, and it is the only mechanism that keeps the paragraph honest.

The economics moved in your favour here. Writing failure tests was always the most tedious work in the flow and it is now the cheap part, which removes the last defensible reason for not having them. A flow whose failure semantics are documented and unexercised is now a choice, and it should be recorded as a risk rather than left as an assumption.

A step that calls a model is non-deterministic, costs money per attempt, may take seconds, and has no natural idempotency — the same prompt twice is not the same answer twice, so a retry is a new result rather than a repeat of the old one. Every bullet on the page needs a different answer for that step.

Two additions are worth making explicit. A tool call with a side effect is a write, and it needs the same idempotency key and retry policy as any other write — an agent looping on a failed tool call is a duplicate-generation policy with better manners. And an autonomous loop needs a stated budget: maximum steps, maximum spend, and the checkpoint at which a person is required. Those are runtime behaviour constraints, they belong beside the flow, and the guardrail that enforces them belongs in the enforcement layer.