Command–Query Separation¶
Method — instantiates Declared Effect Boundary Enforcement
Separates operations that ask for information from operations that change shared state.
Command–Query Separation partitions every operation into one of two kinds: a query, which returns information and is guaranteed to change nothing observable, and a command, which may change shared state and returns only an acknowledgement. Its defining move is to draw the read/write boundary at the interface itself, so a caller can tell from the operation alone whether invoking it can mutate anything — no reading of the implementation required. It says nothing about whether a write is safe, consistent, or reversible; it only fixes which operations are permitted to write and forces them all through a single, visible command channel.
Example¶
A team runs the backend for an online store. The endpoint getCart was supposed to be a harmless read, and callers treated it that way — retried it freely, called it inside loops, fanned it out across pages. In truth it lazily created a cart row on first read and logged a "view" event that decremented a promo-eligibility counter. A read was quietly writing, and nobody calling it knew.
The team applies Command–Query Separation. getCart is rewritten to be a pure query: it returns cart data and touches no durable state, full stop. The cart-creation and view-logging effects are lifted into explicitly named commands (createCart, recordView) that a caller must invoke on purpose, and every such write is routed through one command path. Now the type signatures carry the boundary: getCart cannot mutate, checkout can. A developer reasoning about the code no longer has to guess which "reads" are secretly writes — the interface tells the truth.
How it works¶
- Two-kind partition. Each operation is classified as query or command; nothing is allowed to be both. "Ask a question" and "change the world" never ride in the same call.
- Query purity guarantee. A query may not alter any observable shared state — no lazy initialization, no counters, no incidental writes. If it seems to need one, that need is a command in disguise.
- Single command channel. All mutation is funneled through the command side, so "where can this action write?" has one answer instead of scattered hidden ones.
- Boundary visible at the signature. The read/write split lives in the interface, not a comment, so composability and retry safety of queries become properties a caller can rely on.
Tuning parameters¶
- Purity strictness — whether "query" means no state change at all or no state change a caller can observe (permitting internal caches). Stricter is easier to reason about; looser is easier to implement.
- Command granularity — one broad command versus many narrow ones. Fine commands make the write surface explicit but multiply the interface.
- Naming discipline — how loudly the convention marks commands (verb prefixes, separate types). Louder conventions catch violations in review; quieter ones stay terse.
- Channel centralization — how strictly all writes must pass one command path versus being merely labeled. Central routing is enforceable; labeling is only advisory.
When it helps, and when it misleads¶
Its strength is local reasoning: once queries are truly pure, a caller can invoke, compose, cache, and retry them without fear of hidden mutation, and the entire write surface collapses to the command side where it can be governed.[n1]
Its classic failure is the benign-write temptation — a "harmless" lazy-init, a view counter, a last-accessed timestamp — that slips a real effect back into a query and silently voids the guarantee callers now depend on. And the method is deliberately narrow: it fixes which operations may write, but says nothing about whether those commands preserve invariants or are safe to repeat. The guarding discipline is to police query purity in review and tests, and to pair the split with mechanisms that govern what the commands themselves do.
How it implements the components¶
effect_boundary— the query/command split is the boundary between observation and mutation, expressed in the interface so it matches the real responsibility line rather than the code layout.mutation_gateway— all state change is routed through the command side, making it the single controlled channel through which mutation becomes legitimate.
It does NOT implement protected_invariant_set or idempotency_and_retry_rule — CQS decides which operations may write, not whether a write keeps invariants true or is safe to repeat; that is Immutable Data or Copy-on-Write, its nearest twin, which changes how writes happen rather than which operations may make them.
Related¶
- Instantiates: Declared Effect Boundary Enforcement — draws the read/write boundary and concentrates mutation into a governable channel.
- Sibling mechanisms: Audit Log and Trace · Compensating Action Protocol · Effect Contract Annotation · Effect Review Checklist · Immutable Data or Copy-on-Write · Permission Scope or Capability Token · Sandbox or Staging Execution · State Diff Test · Transaction Boundary
Editorial Notes¶
Form Classification¶
Form family: Structure, Architecture & Configuration
Rationale: Separates operations that ask for information from operations that change shared state, making its operative form a persistent arrangement of components, resources, interfaces, or technical topology.
Independent corroboration: The frozen evidence defines Command–Query Separation as 'Separates operations that ask for information from operations that change shared state', so its operative form is Structure, Architecture & Configuration.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Multi-domain
Rationale: Software design established command-query separation: reads promise no observable mutation, while state changes use explicit command operations.
Review resolution: Both reviewers agree on computer_science as primary. Reading the source mechanism confirms that its defining operation belongs to that lineage; the final record retains no alternate lineage only where it materially formed the mechanism and keeps present-day application breadth separate from provenance.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] Bertrand Meyer's Command–Query Separation principle, from the design of Eiffel, states that a routine should either change state or return a value, but not both. The point is exactly this: asking a question should never, by itself, change the answer. ↩