Handler order is load-bearing in a Chain of Responsibility. What failures does wrong ordering cause, and how do you make order explicit, testable, and safe to extend?

## Why order is a real dependency A Chain of Responsibility turns a conditional cascade into a list of objects. The `else if` sequence was at least visible in one function; the list's order is often produced by classpath scanning, DI registration, or a config file, and no compiler checks it. Order is therefore a **hidden coupling between handlers that never reference each other**. ## Failure mode 1 — shadowing (first-match chains) ``` handlers = [ AnyJsonRequestHandler, InvoiceJsonRequestHandler ] ``` The general handler matches every JSON request, consumes it, and the invoice handler never runs. Symptoms: the specific behavior "mysteriously stops working" after an unrelated deployment; unit tests for the specific handler pass (it is tested in isolation) while the system is wrong. This is the same rule as exception `catch` clause ordering, routing tables, and firewall rules: **most specific first**. Detection: coverage or a counter per handler — a handler that never fires in production is either dead or shadowed. ## Failure mode 2 — prerequisite inversion Some stages establish state that later stages assume: - authentication resolves the principal → authorization needs it - request normalization/decoding → validation and caching need canonical input - rate limiting / quota → must precede expensive work to be useful - tracing/correlation-id → must be first for downstream logs to be attributable - transaction or tenancy context → must wrap the handlers that touch storage Getting these backwards ranges from wasteful (rate limiting after the expensive call) to a security defect (authorization evaluated against an unresolved principal, or a cache keyed on un-normalized input serving one user's data to another). ## Failure mode 3 — ordering that changes results silently In broadcast/enrichment chains everyone runs, so nothing looks broken, but the composed outcome depends on order: two enrichers writing the same field, a sanitizer running after a formatter, a metric recorded before a retry. These are the hardest to catch because there is no missing behavior, only a wrong value. ## Making order explicit 1. **Single owner.** One factory/builder/config that lists the chain top to bottom, read like a script. Scattering `a.next = b` across constructors is the worst case — order is then a property of object graph assembly nobody reviews. 2. **Named phases over numeric priorities.** `@Order(150)` invites priority-number wars between teams; `phase = AUTHENTICATION` with a fixed, small phase sequence gives coarse guarantees and leaves within-phase order irrelevant by design. Reserve numeric ties for genuinely ordered handlers inside a phase. 3. **Declared constraints.** For large plugin sets, let a handler declare `runsAfter(Authentication)` / `runsBefore(Dispatch)` and topologically sort at startup, failing fast on cycles or unsatisfiable constraints. This turns implicit knowledge into a checkable graph. 4. **Disjoint guards.** If handlers' guards are mutually exclusive by construction (dispatch on an enum, on a URI prefix that cannot overlap, on a sealed request type), order stops affecting correctness. This is the strongest fix: prefer a **lookup map keyed by the discriminator** over a scan when the discriminator is exact — the chain earns its keep only when guards are genuinely overlapping or fuzzy. 5. **Exhaustive dispatch checks.** With a sealed/enumerated request hierarchy you can assert at build time that every case has a handler, removing the fall-through class of bugs entirely. ## Testing order - **Golden-order test**: assert the resolved handler sequence (list of class names) equals an expected list. It fails loudly when someone registers a handler, which is exactly the review trigger you want — the diff shows the new position. - **Shadowing test**: for each specific handler, send a request it should own through the *whole* chain (not the handler alone) and assert that handler responded — instrument via a spy, a returned handler id, or tracing. - **Prerequisite test**: send a request that would misbehave under inversion (unauthenticated request to a protected route; over-quota request that is expensive) and assert the early stage short-circuits. - **Property/fuzz check**: for a first-match chain, generate requests and assert at most one handler consumed, and that no handler is never selected across the corpus. ## Observability - Log the composed chain **once at startup** (ordered class names + phase) — this single line resolves most "why did it behave differently in staging" questions. - Per request, record the traversal path or at least the terminal handler id (a span/attribute, a response header in non-production, a structured log field). Without it, the pattern's runtime indirection becomes an operational blind spot. - Per-handler counters (invocations, matches) reveal dead and shadowed handlers. ## Extension policy When a chain is an extension point for other teams or plugins, order becomes a public contract. Publish it: the phase list, what each phase may assume, whether a handler may consume, and whether it may mutate the request. Otherwise every new plugin author guesses, and the guesses collide.