Failure boundaries and honest retry guarantees

This lesson uses the behavioral-contracts.zip runtime comparison API. Its policies differ deliberately from core behavioral-patterns.zip; see the contract comparison.

What this concept is

A command records intent; it does not by itself guarantee atomic execution, persistence, serializability or exactly-once effects. Define where the effect happens, where success is recorded and what a retry can observe.

Why it matters here

The same vocabulary is used for in-memory actions and remote operations, but their failure models differ. This lesson connects local design to later systems work without claiming to implement a distributed protocol.

Concrete example

Suppose a SendEmail handler sends first and then records its ID. A crash between those steps leaves an unrecorded effect; retry may send twice. Recording first creates the opposite window: a crash may suppress a message never sent. A local set of processed IDs cannot atomically cover a separate remote email service.

Common confusion / misconception

An idempotency key is not an exactly-once guarantee. Its useful behavior depends on scope, retention, concurrent requests, same-key/different-payload handling, and coordination with the actual effect. Undo is also not compensation: a compensating action may be a new effect with its own failures.

How to use it

For the local lab, promise only single-threaded in-memory semantics and explicit exception policy. For remote commands, specify receiver-supported deduplication or transactional coordination where possible; otherwise expose an uncertain outcome and reconciliation. Preserve the same key for the same logical retry, reject conflicting intent, and state expiry. Later systems/production material must supply durable implementation and failure testing.

Check yourself

Why does collecting observer exceptions not make all callbacks atomic? If A changes external state and B fails, what can the publisher safely report?

Mini drill or application

Draw the two crash windows in send-then-record and record-then-send. Write a result vocabulary separating rejected, locally committed and uncertain remote outcome. Contrast this with the editor, whose invalid edit is guaranteed not to change local state.

Read this only if stuck

Use the existing book/reference map and runtime reading guide. The Design Patterns book index supplies pattern vocabulary; the local lab contract specifies its actual semantics.