DEV Community: Andrii B.

Restate's Single Binary vs Temporal's Cluster: When the Lighter Engine Wins

Andrii B. — Sun, 09 Aug 2026 19:05:41 +0000

Here is a bet that will save you a lot of arguing: pick your durable execution engine on what you have to operate, not on what you have to write. The code you write for Restate and the code you write for Temporal end up looking more alike than either vendor wants to admit. They both journal every step and replay it after a crash so your half-finished order doesn't get charged twice. What actually differs, and what you'll be living with at 2am, is the shape of the thing you have to run. One is a single binary. The other is a cluster of four services with an external database bolted to the side.

That's the whole article in one sentence, but the sentence hides all the interesting parts: when the cluster is exactly what you want, when it's a tax you're paying for nothing, and why "single binary" isn't quite as simple as it sounds either. Let's get specific, because the marketing on both sides is loud and the honest version is more useful.

The same problem both are solving

Durable execution is a narrow, beautiful idea. Your code runs a multi-step operation: charge the card, reserve the inventory, send the email, mark the order shipped. Halfway through, the process dies. A normal service loses everything in memory and you're left reconciling a card that got charged against inventory that never got reserved. A durable execution engine writes each completed step to a journal, and when the process comes back it replays that journal, skips the steps that already finished, and continues from exactly where it stopped. No double charge, no lost reservation.

Both Restate and Temporal do this. Both do it well. So the first thing to throw out is any pitch that frames one as "durable" and the other as "less durable." They are both real durable execution engines built on journal-and-replay. If someone is selling you on durability itself as the differentiator, they're selling you the thing you get from either one. The differentiator is everything around the journal: where it lives, what runs it, and what your app has to become to use it.

Temporal is a cluster, and your app becomes two services

Temporal's server is not one process. It's four independently scalable services: a Frontend that acts as the gateway (routing, rate limiting, auth), a History service that owns the mutable workflow state and timers, a Matching service that hosts the task queues that dispatch work, and an internal Worker service for Temporal's own system workflows. Each is a separate process with its own gRPC endpoint, and the whole point of splitting them is that you scale them independently when you're big enough to need that.

That cluster can't remember anything on its own. It requires an external database for persistence: PostgreSQL or MySQL in practice (SQLite exists for local dev). If you were about to reach for Cassandra because an old blog post told you to, don't: Cassandra was deprecated in Temporal Server v1.21 and removed in v1.24. And once you spawn more than a handful of workflows and want to search them by anything richer than an ID, you're looking at Elasticsearch or OpenSearch. That last one is a genuine nuance the internet gets wrong in both directions: SQL databases have supported Advanced Visibility since Server v1.20, so Elasticsearch is not strictly required. It's recommended once your volume grows. "Temporal always needs Elasticsearch" is a myth; "you'll probably want it eventually" is the truth.

Then there's your own code. In Temporal, your workflow logic runs inside a Worker, a process that hosts your workflow and activity code and long-polls the cluster's task queues for work. That worker is a separate deployable from your API. So adopting Temporal isn't just "run a server." It's: stand up the cluster, attach a database, probably add a search cluster later, and split your application into an API service plus a worker service that both depend on the Temporal server being up. Here's the shape of the code that runs in that worker:

// activities.ts - the side effects, retryable, run in a normal runtime
export async function greet(name: string): Promise<string> {
  return `Hello, ${name}!`;
}

// workflows.ts - orchestration, and it must be deterministic
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { greet } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
});

export async function example(name: string): Promise<string> {
  return await greet(name);
}

Notice you don't call greet directly from the workflow. You go through proxyActivities, because the workflow code is replayed from its event history on every recovery and must be deterministic: the same input has to produce the same sequence of commands every time, or Temporal raises a nondeterminism error and refuses to continue. That constraint is the price of Temporal's replay model, and it's a real thing you have to design around (no Date.now() in a workflow, no random, no direct I/O). Temporal Cloud exists precisely so you don't have to run the cluster and database yourself, and if you're going to commit to Temporal at scale, paying them to operate it is usually the sane choice.

Restate is one binary, and the database is already inside it

Restate takes the opposite bet. The server is a single binary written in Rust with a stream-processing architecture, and it carries its own storage: an embedded RocksDB key-value store holds the journal and the durable state. There is no external Postgres to provision, no Elasticsearch to babysit. You download one binary, you run it, and you have durable execution.

The honest asterisk, because Restate's own comparison page glosses over it: "single binary" does not mean "single process and nothing else" once you care about high availability. For HA you run several instances of that binary, and RocksDB periodically snapshots to an object store (S3, GCS, or Azure Blob) so a node can fail and another can recover the state and trim its logs. So the real comparison isn't "one process vs a cluster." It's "several copies of one binary plus a bucket" versus "four service types plus a relational database plus an optional search cluster plus your own split-out worker." That's still a dramatic difference in operational surface, but say it accurately or someone will call your bluff in the comments.

The programming model is ordinary-looking service handlers that Restate journals for you:

import * as restate from "@restatedev/restate-sdk";

export const myService = restate.service({
  name: "MyService",
  handlers: {
    myHandler: async (ctx: restate.Context, greeting: string) => {
      return `${greeting}!`;
    },
  },
});

restate.serve({ services: [myService] });

Restate's distinctive primitive is the Virtual Object: a stateful entity keyed by an id, with its own isolated key-value state and a single-writer guarantee, so only one handler mutates a given object's state at a time. It's durable keyed state without you standing up a separate store for it:

import * as restate from "@restatedev/restate-sdk";

export const myObject = restate.object({
  name: "MyObject",
  handlers: {
    myHandler: async (ctx: restate.ObjectContext, greeting: string) => {
      return `${greeting} ${ctx.key}!`;
    },
  },
});

restate.serve({ services: [myObject] });

Restate also gives you durable promises (awakeables) to wait on external events, and durable timers via ctx.sleep, all tracked across failures. It has SDKs for TypeScript, Java and Kotlin, Python, Go, and Rust. And crucially, it does not impose Temporal's hard determinism contract on your handler in the same way: the durable steps go through the context, and the framework replays the journal rather than re-running your whole function as strictly-deterministic orchestration. The scope is also framed more broadly. Temporal sells itself as workflow orchestration; Restate positions as durable execution for "any part of your backend," workflows, agents, microservices, event handlers. Whether that breadth matters to you is a real question, not just a slogan.

The programming models diverge more than the marketing admits

It's tempting to say "they're both durable execution, the code is basically the same." It isn't, and the difference is exactly the kind of thing that bites you six months in.

Temporal's model is a hard split between deterministic workflows and side-effecting activities, enforced by replay. That split is powerful: it's what lets a workflow sleep for thirty days and wake up with its local variables intact, because Temporal isn't keeping your process alive, it's replaying your workflow's event history to reconstruct that state on demand. But it means your orchestration code lives under a determinism microscope. Every nondeterministic thing you're used to reaching for is a landmine, and "why did my workflow throw a nondeterminism error after I changed the code" is a rite of passage.

Restate's model asks less of your mental model up front: you write handlers, you use the context for the durable operations, and durable keyed state is a Virtual Object rather than a workflow-scoped variable you're forbidden from computing nondeterministically. For a lot of backend work, "make this handler crash-proof and give it some durable state" is all you wanted, and you get it without adopting the full workflow-orchestration worldview. The flip side: Temporal's worldview, once you've paid for it, is genuinely better at the gnarliest long-running orchestration, and its retry and timeout configuration is deeper.

So how much of this is code, and how much is ops?

This is where the "mostly ops, not code" claim earns or loses its keep. The code delta is real but modest: with either engine you annotate or restructure some functions and route durable steps through a context. The operational delta is not modest at all.

There's a widely-cited number here, and it's worth handling honestly because it's easy to misuse. DBOS, which is itself a competitor to both, published a benchmark where adopting Temporal on a sample app meant changing more than 100 lines, growing the app from 110 to 187 total lines, and splitting it into two services (a worker and the API) with a runtime dependency on a third (the Temporal server), three tightly-coupled services where any one going down takes the other two with it. That's a vendor's benchmark of DBOS versus Temporal, on one sample app, so don't quote it as a law of nature and definitely don't attribute it to Restate. But the architectural claim underneath it is neutral and verifiable straight from Temporal's own docs: your workflow code runs in a separate worker deployable, and the cluster plus its database are separate infrastructure. That part isn't marketing. It's how Temporal is built.

For Restate versus Temporal specifically, I couldn't find a clean neutral lines-of-code comparison, so I won't invent one. What I can say from the architecture is the honest version: standing up Restate is downloading a binary and pointing it at an object store; standing up Temporal is running a four-service cluster, attaching Postgres, planning for a search cluster, and splitting your app into API-plus-worker. If your instinct is that those are not remotely the same amount of ops, your instinct is correct, and no amount of "but Temporal Cloud makes it easy" changes the fact that you either run all of that or pay someone to.

When the heavier engine earns it

None of this means Temporal is overkill. It means Temporal is priced for a specific job, and when you have that job, the cluster is a bargain.

Reach for Temporal when your workflows are genuinely long and human-timescale: things that sleep for days, weeks, or months and must survive every deploy and restart in between. Reach for it when you need deep, per-activity control over retries and multiple timeout types, when you want the largest ecosystem and the most battle-tested SDKs across TypeScript, Java, Python, Go, .NET, and PHP, and when scale and multi-region operation are real requirements rather than aspirations. Two 2026 signals matter here: Temporal Cloud gives you managed multi-region so you're not operating that cluster yourself, and Temporal Nexus is now generally available, which lets teams compose durable executions across isolated namespaces, regions, and clouds with per-team blast-radius isolation. If your problem is "twelve teams each own a namespace and need to call each other's durable workflows without sharing a database," that's a Temporal-shaped problem, and Restate isn't trying to be the answer to it.

When the lighter engine wins

Here's the part the title promised. The lighter engine wins far more often than the "we're an enterprise, we need Temporal" reflex assumes.

Restate wins when your durable needs are "don't lose this multi-step operation and give it some durable state," not "orchestrate month-long sagas across a dozen teams." It wins when the operational budget is the constraint, when a single binary plus an object store is a Tuesday and a four-service cluster plus a database plus a search cluster is a quarter of platform work you didn't want to fund. It wins when you want durable execution to sit inside your normal backend, your services, your event handlers, the agent you're building this year, rather than forcing everything through a workflow-orchestration frame. And it wins on adoption speed: the fastest way to have durable execution running in an afternoon is the one that doesn't start with provisioning a cluster.

So the verdict, stated as a decision rule you can actually use: default to the lighter footprint, and only take on Temporal's cluster when you can name the specific Temporal feature you need that Restate doesn't give you. Month-long timers with per-step retry policies. Cross-namespace composition through Nexus. Battle-tested operation at a scale you're actually at, not the scale on your roadmap. Those are real reasons, and when they're your reasons, pay the operational tax gladly. But if you're standing up a Postgres, an Elasticsearch, and a two-service split to make a five-step checkout crash-proof, the engine isn't the thing that's overbuilt. The decision was. Both of these journal and replay. Pick the one whose operations page you'd actually enjoy owning.

PS: English is not my native language, so I used AI to help with proofreading and phrasing. All ideas and technical content are my own.

Originally published at andriiboyko.com.

If you found this helpful, follow me here and on LinkedIn

You Probably Don't Need a Dedicated Vector Database

Andrii B. — Fri, 07 Aug 2026 09:44:00 +0000

Somewhere in the last two years, "we're doing RAG" quietly became "so we need a vector database," and the second half of that sentence stopped getting questioned. You add Pinecone or Qdrant or Weaviate to the stack, wire up a sync job, and now you own two datastores that have to agree with each other forever. For a demo, fine. For most production systems, you just bought a distributed-systems problem to solve a problem you didn't have.

Here's the number that should have ended the debate before it started: pgvector, the vector extension that runs inside the Postgres you're already paying for, handles vector search comfortably into the low tens of millions of vectors on a single node. Not "for toy projects." Into the tens of millions. And it does it while your embeddings sit in the same transaction, the same backup, and the same WHERE tenant_id = ? as the rest of your data. The dedicated vector database is a real tool with a real job. That job just starts a lot further up the scale curve than the people selling it want you to think.

What a vector database actually does

Strip away the marketing and a vector database does one thing: approximate nearest-neighbor search over high-dimensional embeddings. You have a query vector, you have millions of stored vectors, and you want the closest few by cosine or L2 distance without comparing against every single one. The trick that makes it fast is an index, almost always HNSW (Hierarchical Navigable Small World), a graph you walk to find close neighbors in roughly logarithmic time instead of scanning the whole set.

That's it. That's the special sauce. And Postgres has had it since pgvector 0.5.0 shipped HNSW back in 2023. Here's the entire "vector database" you need for most apps:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE chunks (
  id         bigserial PRIMARY KEY,
  doc_id     bigint NOT NULL REFERENCES documents(id),
  tenant_id  bigint NOT NULL,
  content    text,
  embedding  vector(1536)          -- e.g. OpenAI text-embedding-3-small
);

-- The index that makes it fast. m and ef_construction trade build time for recall.
CREATE INDEX ON chunks USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

A nearest-neighbor query is an ORDER BY on a distance operator (<=> is cosine distance, <-> is L2, <#> is negative inner product):

SELECT id, content
FROM chunks
ORDER BY embedding <=> $1     -- $1 is your query embedding
LIMIT 10;

That query, against an HNSW index that fits in memory, is not meaningfully slower than the same query against Pinecone at the scales most teams operate at. Benchmarks have pgvector with HNSW matching or beating dedicated engines at around 1M vectors. So the honest question isn't "is pgvector good enough" at a million vectors. It obviously is. The question is what you give up by not adding a second system, and the answer is: nothing. You gain things.

The stuff you get for free (and would have to rebuild)

This is the part the comparison charts leave out, because it doesn't fit in a QPS column. When your vectors live in Postgres, every other thing Postgres does applies to them at the same time.

Filtering and multi-tenancy are just a WHERE clause. Real RAG is almost never "search all vectors." It's "search this tenant's documents," or "search docs this user can see, from the last 90 days, in the 'published' state." In Postgres that's the query you already know how to write, and it runs in the same index scan:

SELECT c.id, d.title, c.content
FROM chunks c
JOIN documents d ON d.id = c.doc_id
WHERE c.tenant_id = $1
  AND d.status = 'published'
ORDER BY c.embedding <=> $2
LIMIT 10;

Look at that JOIN. Your embedding result comes back already stitched to the document's title, its author, its permissions, whatever you need, in one round trip. In a dedicated vector store you get back a list of IDs, and then you make a second call to Postgres to hydrate them, and now you're doing a distributed join by hand in application code and hoping the two systems didn't drift.

Row-level security means tenant isolation you can't forget. You can push tenancy down into the database so a missing WHERE clause can't leak one customer's chunks into another's results:

ALTER TABLE chunks ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON chunks
  USING (tenant_id = current_setting('app.tenant_id')::bigint);

Try enforcing that in a separate vector database. You can't, really, not at the storage layer. Tenant isolation becomes an application concern you re-implement and re-audit, which is exactly the kind of thing that turns into a security incident.

One transaction, one backup, one truth. When you insert a document and its chunks and their embeddings, that's one transaction. It commits or it doesn't. There's no window where the document exists but its vectors don't, or where you deleted a record but its embedding is still floating in another system returning ghosts in search. Your existing backup, your existing replica, your existing point-in-time recovery already cover the vectors. You didn't add an operational surface. You added a column.

That "one truth" point is the whole argument, honestly. The moment you split vectors into their own store, you own a synchronization problem: dual writes, eventual consistency between your source of truth and your search index, reconciliation jobs, and the 3am question of why a deleted record still shows up in RAG results. That problem is real work, and you took it on to save a latency difference you can't measure yet.

The two gotchas that actually bite

pgvector is not magic, and pretending it has no sharp edges is how you end up back in the dedicated-database camp for the wrong reasons. There are exactly two things that bite people, and both have answers.

Gotcha one: the HNSW index has to fit in memory. The single biggest factor in pgvector performance is whether the HNSW graph lives in RAM. When the index fits in shared_buffers and stays there, queries are fast and boring. When it spills to disk because the index outgrew memory or got evicted under load, tail latency falls off a cliff. So capacity-planning pgvector is really memory-planning: know your vector count times your dimensions times the index overhead, and make sure it fits with headroom. A 1536-dimension vector is about 6KB raw; ten million of them plus HNSW overhead is a real but very ordinary amount of RAM for a database server in 2026. This is also where halfvec earns its keep: store embeddings as 16-bit floats and you roughly halve the memory, which for 3072-dimension models is the difference between fitting and not.

Gotcha two: filtered search used to quietly return too few rows. This one burned people for years and is the single most common "pgvector is broken" complaint. Before pgvector 0.8.0, the HNSW index returned its candidate set first, and then your WHERE tenant_id = ? filter ran on that set. If your filter was selective, you'd ask for 10 results and get 3, because 7 of the index's candidates belonged to other tenants and got dropped after the fact. It looked like a correctness bug and it was really an ordering-of-operations problem.

pgvector 0.8.0 fixed it with iterative index scans: the planner keeps pulling more of the index until enough rows survive your filter. You turn it on per-session:

SET hnsw.iterative_scan = relaxed_order;   -- keep scanning until LIMIT is satisfied
-- strict_order preserves exact distance order; relaxed_order trades a little
-- ordering for better recall under selective filters.
-- Bounds: hnsw.max_scan_tuples (default 20000), hnsw.scan_mem_multiplier (default 1).

SELECT id, content
FROM chunks
WHERE tenant_id = $1
ORDER BY embedding <=> $2
LIMIT 10;

If you evaluated pgvector before 0.8.0, hit the filtered-search wall, and concluded you needed a "real" vector database, that conclusion is now out of date. Re-check it. The version number matters here more than almost anywhere else in the Postgres world.

When you actually do need one

The contrarian take isn't "never use a dedicated vector database." It's "know the line, and don't cross it before you get there." The line is real, and it's roughly this:

Under roughly 10 million vectors, pgvector with a well-tuned HNSW index that fits in RAM matches or beats dedicated engines, and you keep all the free stuff above. From about 10 to 50 million, plain pgvector starts to strain, but you don't have to leave Postgres yet: the pgvectorscale extension adds a StreamingDiskANN index that stays fast when the dataset is larger than RAM, plus statistical binary quantization to shrink memory and label-aware filtering. In one benchmark it hit 471 queries per second at 99% recall on 50 million vectors, about 11 times Qdrant's throughput at the same recall. So the "you'll outgrow Postgres" story has a whole extra chapter before it's even true.

Past 50 to 100 million vectors, or when your workload is vector-search-first with brutal tail-latency SLAs and you want someone else to operate the scaling, the dedicated engines genuinely pull ahead. Pinecone is the fastest path to zero-ops scaling toward billions. Qdrant wins raw QPS and filtering if you want to stay open-source and run it yourself. Weaviate bundles embedding generation so you can hand it raw text. These are good products solving a real problem. They're just solving a problem that starts at a scale most applications will never reach, and they charge you the two-system tax the entire way there.

The mistake almost nobody regrets avoiding is starting on pgvector and migrating later. Moving 100 million vectors to a dedicated store when you actually hit the wall is a known, boring data-migration project you'll have the revenue to staff. Standing up a second stateful system on day one to serve 200,000 vectors is how you spend your scaling budget before you have anything to scale. Put the embeddings in the database that already holds your data, add the vector column, ship the feature, and add the dedicated engine the day the numbers, not the demo, tell you to.

Originally published at andriiboyko.com.

If you found this helpful, follow me here and on LinkedIn

The Orchestrator-Subagent Pattern, Modeled as a Domain

Andrii B. — Mon, 27 Jul 2026 12:56:21 +0000

Give a language model a slightly better prompt and you might squeeze out a few percent. Give it a second copy of itself to delegate to, and Anthropic measured a 90.2% jump on research tasks over the same model working alone. Here's the part that should bother you: the improvement had almost nothing to do with the models getting smarter. The lead agent and the workers ran the same family of models. What changed was how the work got divided.

That's not a machine-learning result. It's a domain-modeling result. And it points at something most teams building agent systems get backwards: the hard parts of multi-agent orchestration aren't the prompts or the model choice. They're boundaries, invariants, and failure handling, which is to say they are exactly the problems domain-driven design was built for. This is the same lens the CQRS and credentialing pieces used on ordinary backends, pointed at the agent stack.

The Pattern, Stated Plainly

The orchestrator-subagent pattern (sometimes orchestrator-worker) is simple to describe. A lead agent takes a goal, plans an approach, and spins up a handful of subagents, typically three to five, each with a narrow mandate. The subagents run in parallel. When they finish, the lead agent synthesizes their results into an answer, often with a separate citation or verification pass at the end.

The crucial detail, the one that makes the whole thing work and also makes it hard: each subagent runs in its own context window, with its own tools and its own exploration trajectory. The orchestrator hands out an assignment and gets back a result. It never sees the subagent's intermediate reasoning, the dead ends, the forty tool calls it took to get there. Only the finished product comes back.

If that arrangement sounds familiar, it should. You have already been modeling systems where one component gives another an instruction and receives only a result, with the internals sealed off. That is an aggregate boundary, and treating it as one is the whole game.

The Context Window Is an Aggregate Boundary

In DDD, an aggregate is a cluster of objects you treat as a single unit, with a root that is the only legal way in. You don't reach into an aggregate and read its internals. You send its root a message and it hands you back a result. The internal reasoning stays private.

A subagent's context window is exactly this boundary, enforced by the runtime instead of by discipline. The orchestrator physically cannot see inside a subagent's window. It gets the published result and nothing else. Which means the thing coming back across that boundary deserves to be modeled as a proper value object, not a bag of loose strings:

// The result is the ONLY thing that crosses the boundary.
// Model it as a value object with provenance, not a raw string.
class SubagentResult {
  private constructor(
    readonly taskId: string,
    readonly findings: string,
    readonly sources: Source[],
    readonly tokensSpent: number,
    readonly completedAt: Date,
  ) {}

  static fromCompletion(raw: SubagentCompletion): SubagentResult {
    if (raw.sources.length === 0) {
      // A "finding" with no sources is not a result. It's a claim.
      throw new DomainError(`Subagent ${raw.taskId} returned findings with no sources`);
    }
    return new SubagentResult(
      raw.taskId, raw.findings, raw.sources, raw.tokensSpent, raw.completedAt,
    );
  }
}

The same move as the credentialing article's VerifiedCredential: a private constructor and a single factory that enforces an invariant at the boundary. There, a credential couldn't exist without primary-source verification. Here, a result can't exist without sources. The orchestrator's synthesis step then gets to assume every result it holds already cleared that bar, instead of re-checking each one defensively.

The Orchestration Is the Aggregate Root

So what owns the invariants? Not the subagents, they're isolated by design and don't know about each other. The orchestration run itself is the aggregate root. It's the thing that holds the goal, tracks which tasks are outstanding, and enforces the one rule that matters most.

That rule is a guard you have seen before: don't synthesize until every delegated task has resolved. In the credentialing domain it was "you can't send a file to committee review with a hole in it." Same shape here:

class Orchestration {
  private status: OrchestrationStatus = OrchestrationStatus.Planning;
  private tasks: Map<string, TaskState> = new Map();
  private results: SubagentResult[] = [];

  synthesize(): Answer {
    const unresolved = [...this.tasks.values()].filter((t) => !t.isResolved());
    if (unresolved.length > 0) {
      throw new DomainError(
        `Cannot synthesize with ${unresolved.length} task(s) still outstanding`,
      );
    }
    this.status = OrchestrationStatus.Synthesizing;
    return Answer.from(this.results);
  }
}

Nothing about this is AI-specific. It's an aggregate refusing to enter an invalid state. The fact that the "tasks" happen to be language models exploring the web is an implementation detail the invariant doesn't care about.

The Bug Is a Missing Invariant

Here's a real failure the Anthropic team reported: the orchestrator would sometimes get over-enthusiastic and spawn fifty subagents for a question that needed two. Others would spin in loops chasing sources that didn't exist.

It's tempting to read that as the model being flaky. It isn't, or at least that's not the useful reading. Spawning fifty workers is what happens when delegation is an unbounded loop with no invariant guarding it. The domain has a rule, fan-out has a sane ceiling, and if that rule doesn't live anywhere in the model, the model has no way to honor it. So you put it where rules go, in a policy the aggregate consults, not a magic number buried in a prompt:

class FanOutPolicy {
  constructor(private readonly maxSubagents: number) {}

  admit(current: number, requested: number): number {
    // Never exceed the ceiling. Return how many we can actually spawn.
    return Math.max(0, Math.min(requested, this.maxSubagents - current));
  }
}

This reframing matters because of where agent systems actually break. One study of failures across seven multi-agent frameworks, AG2 (formerly AutoGen), MetaGPT, and ChatDev among them, found that coordination failures, what the authors call inter-agent misalignment, accounted for 36.94% of everything that went wrong. Fold in the 41.77% they pinned on specification and system design, and more than three-quarters of failures trace to design and coordination, not to the model being dumb. The boundaries between agents are where the bugs live. That's a domain-design problem with a domain-design fix.

Subagent Results Are External Events, Not Return Values

Now the part that makes this genuinely harder than a credentialing case, and where you have to break the analogy.

In an ordinary domain, transitions are deterministic. Approve a clean file and it becomes approved, every time. A subagent is not deterministic. Hand the same mandate to the same model twice and you can get two different trajectories, two different token costs, and occasionally a worker that never comes back at all. You cannot model a subagent call as a function that returns a value. You have to model it as something that might arrive, might fail, or might hang, arriving from outside your control.

Which, again, is a shape the credentialing model already had: the sanction that could land at any time and knock an approved provider into suspension. An outside event the aggregate has to be ready for. Delegation is the same. Every subagent is a potential SubagentFailed or SubagentTimedOut waiting to happen, and the orchestration has to stay valid when it does:

onSubagentTimedOut(taskId: string): DomainEvent[] {
  const task = this.tasks.get(taskId);
  if (!task || task.isResolved()) return [];
  // A timeout resolves the task as failed, not as pending forever.
  task.markFailed("timeout");
  // The whole run is degraded, but it is NOT dead. Partial answers beat none.
  return [new SubagentFailed(this.id, taskId, "timeout")];
}

Marking the task failed is what keeps synthesize()'s guard honest. A timed-out worker is a resolved task, so the run can still complete on the results it did get, degraded but alive, rather than blocking forever on a subagent that is never coming back. The rule "don't wait on the dead" is a domain rule, not a networking detail.

Cost Is a Domain Rule

There's one invariant this domain has that most don't, and it's expensive to ignore. Multi-agent runs are costly. Anthropic put the figure at roughly fifteen times the tokens of a normal chat, and found that token usage alone explained about 80% of the performance variance in one of their benchmarks. Spend is not a side effect here. It's close to the primary lever.

That makes a token budget a first-class invariant, the same way the 36-month clock was in the credentialing model. The aggregate owns a budget and refuses to over-delegate past it, so a single runaway question can't quietly burn the month's spend:

delegate(tasks: TaskMandate[], budget: TokenBudget, policy: FanOutPolicy): TaskMandate[] {
  const slots = policy.admit(this.tasks.size, tasks.length);
  const affordable = budget.remaining() > 0 ? slots : 0;
  if (affordable === 0) {
    throw new DomainError("Fan-out blocked: budget exhausted or ceiling reached");
  }
  return tasks.slice(0, affordable);
}

If you have ever wired FinOps guardrails into a platform, this is the same idea moved one layer up: enforce the budget at the moment of spend, not in a dashboard you read afterward.

When the Boundary Is Wrong

The honest limit, because this pattern is oversold right now. The isolation that makes orchestration powerful is also its hard constraint. Subagents can't see each other's reasoning, only the orchestrator can, and only the finished results at that. That's a fantastic fit for breadth-first work: research a topic from five angles at once, explore independent branches, gather in parallel. It's a terrible fit for tightly coupled work where each step depends on the intermediate state of the last, because the boundary you're relying on is precisely the thing blocking that state from flowing.

In DDD terms, this is a diagnosis you already know how to make. If two aggregates constantly need to reach into each other's internals to do their jobs, they aren't two aggregates. You drew the boundary in the wrong place, and they should be one. Same rule here: if your subagents keep needing each other's half-finished thoughts, multi-agent isn't buying you anything, and the isolation is pure overhead on top of a 15x bill. Collapse it back into one agent with one context and move on.

Which is the quiet punchline. The interesting questions in agent engineering right now are not "which model" or "what prompt." They're "where does this boundary go," "what invariant holds this together," and "what happens when a piece of it fails." We have had good answers to those questions for twenty years. They just never had this particular costume on before.

Originally published at andriiboyko.com.

Declarative Agent Workflows in Go: What Microsoft Shipped, and What You Build Yourself

Andrii B. — Sat, 25 Jul 2026 12:11:04 +0000

In June 2026 Microsoft shipped declarative workflows for its Agent Framework at 1.0. The pitch is good: you describe a multi-agent workflow in a YAML file instead of wiring it in code, so a workflow becomes a config artifact you can read, diff, version, and hand to someone who doesn't write code. The agent-framework-declarative package went 1.0.0 on PyPI, joining the already-stable .NET Microsoft.Agents.AI.Workflows.Declarative.

Then you open the docs, flip the language pivot to Go, and the how-to isn't there. Declarative workflows are a Python and .NET feature. The Go SDK, github.com/microsoft/agent-framework-go, is in public preview, and its own release notes are blunt about the gap: declarative agents, RAG, CodeAct, and functional workflows "are not yet available."

So if you're building agent systems in Go, you're in an interesting spot. The concept Microsoft is selling is genuinely useful. The runtime that would give it to you exists in your language. The thin YAML-to-graph layer on top just hasn't been written for Go yet. That's a gap you can close in about a hundred lines, and by the end of this you'll have. But first, let's be precise about what "declarative" is actually buying you, because half the teams that reach for it don't need it.

What "declarative" actually means here

A programmatic workflow is code. You import a builder, instantiate executors, connect them, and call Build(). A declarative workflow is the same graph expressed as data. Here's the Python-flavored version straight from the docs, a workflow that greets someone by name:

name: greeting-workflow
description: A simple workflow that greets the user

inputs:
  name:
    type: string
    description: The name of the person to greet

actions:
  - kind: SetVariable
    id: build_message
    variable: Local.message
    value: =Concat("Hello, ", Workflow.Inputs.name, "!")

  - kind: SendActivity
    id: send_greeting
    activity:
      text: =Local.message

Two things worth noticing. First, every step has a kind. The framework ships a fixed vocabulary of them, and that vocabulary is the whole point: SetVariable, If, ConditionGroup, Foreach, InvokeAzureAgent, InvokeFunctionTool, InvokeMcpTool, HttpRequestAction, Question, SendActivity, and a dozen more. You're not writing behavior, you're picking from a menu of pre-approved building blocks. That constraint is a feature. It's what lets a non-developer safely edit the file.

Second, look at the value fields that start with =. Those are expressions, evaluated at runtime by an embedded expression engine. Microsoft uses PowerFx here, the same formula language behind Power Apps, so =Concat("Hello, ", Workflow.Inputs.name) is a real function call, not string templating. Variables live in namespaces: Local.* for workflow-scoped state, Workflow.Inputs.* and Workflow.Outputs.* for the contract with the caller, and System.* for framework-provided values like System.ConversationId and System.LastMessage.

The docs include a decision table that's more honest than most vendor tables, so it's worth reproducing:

Scenario	Recommended
Standard orchestration patterns	Declarative
Workflows that change frequently	Declarative
Non-developers need to modify workflows	Declarative
Complex custom logic	Programmatic
Maximum flexibility and control	Programmatic
Integration with existing code	Programmatic

Read the right column. The moment your workflow needs anything the action vocabulary doesn't cover, you're back in code. Declarative isn't a more powerful way to build workflows, it's a more constrained one, and the constraint is the value. Keep that in mind, it's the whole argument for when to bother.

There's also a gotcha hiding in that expression engine. On Python the declarative package supports 3.10 through 3.13 and explicitly not 3.14, "due to PowerFx compatibility." When your workflow definition language is coupled to a .NET formula runtime, that runtime's portability becomes your portability. Hold that thought, it's part of why the Go story is what it is.

The catch: Go isn't invited to this party yet

Here's the state of play as of mid-2026. Declarative workflows are 1.0 on Python and .NET. On Go, they don't exist. The Go SDK is public preview and the feature list that's shipped covers agents, providers, tools, and programmatic workflows. The declarative layer, the RAG helpers, CodeAct, and functional workflows are all on the "coming" side of the line.

That could read as "Go is behind, come back later." I'd read it differently. The reason declarative is hard to port isn't the graph engine, Go already has that. It's PowerFx. Porting the declarative feature faithfully means either binding a .NET expression runtime into a Go process or reimplementing PowerFx, and neither is a weekend. The valuable part, turning a YAML graph into a running workflow, is the easy part. That's the part you can do yourself today.

So the plan for the rest of this piece: see what the Go SDK's programmatic workflows actually look like, understand the engine underneath them (it's more interesting than you'd expect), and then build a small declarative layer that compiles YAML into that engine. Real Go, runs today.

What the Go SDK gives you today

The programmatic API is clean. You create executors, which are just processing units, and connect them with edges. Here's the canonical example from the Go docs, verbatim, a two-stage pipeline that uppercases a string then reverses it:

import (
    "github.com/microsoft/agent-framework-go/workflow"
    "github.com/microsoft/agent-framework-go/workflow/inproc"
)

uppercase := workflow.NewExecutor("UppercaseExecutor", func(input string) string {
    return strings.ToUpper(input)
}).Bind()

reverse := workflow.NewExecutor("ReverseExecutor", func(input string) string {
    runes := []rune(input)
    slices.Reverse(runes)
    return string(runes)
}).Bind()

wf, err := workflow.NewBuilder(uppercase).
    AddEdge(uppercase, reverse).
    WithOutputFrom(reverse).
    Build()
if err != nil {
    return err
}

An executor is any function with a shape like func(input) output, wrapped by NewExecutor and registered with Bind(). The builder takes a starting executor, you AddEdge from one to the next, mark which executor's output is the workflow output with WithOutputFrom, and Build(). Then you run it, streaming events as they happen:

stream, err := inproc.Default.RunStreaming(context.Background(), wf, "Hello, World!")
if err != nil {
    return err
}
defer stream.Close(context.Background())

for evt, err := range stream.WatchStream(context.Background()) {
    if err != nil {
        return err
    }
    if output, ok := evt.(workflow.OutputEvent); ok {
        fmt.Printf("Workflow completed: %v\n", output.Output)
    }
}

Note the for ... range over a function, that's a Go 1.23 range-over-func iterator. The SDK's go.mod actually requires Go 1.25, so it was written for a very recent Go and leans hard into the new language features. There's a non-streaming inproc.Default.Run too, which collects events so you can walk them after the fact with run.NewEvents().

That's a straight line. The interesting cases are branches. The builder exposes conditional routing through a switch, so you can send a message down different paths based on its content. In preview the shape looks like this (treat the exact method names as preview-era, the repo is the source of truth):

wb := workflow.NewBuilder(classify)

wb.AddSwitch(classify).
    AddCase(func(m any) bool { return m.(Ticket).Category == "billing" }, billing).
    AddCase(func(m any) bool { return m.(Ticket).Category == "technical" }, technical).
    WithDefault(general).
    AddToBuilder(wb)

wf, err := wb.WithOutputFrom(billing, technical, general).Build()

There's more in the same family: AddFanOutEdge to broadcast to several executors, AddFanInBarrierEdge to join them back, AddChain for a straight sequence, and RequestPort for human-in-the-loop, where the workflow pauses and raises a request event that you answer from outside. And Build() isn't a rubber stamp. It validates the graph: type compatibility between connected executors, that every executor is reachable from the start, that bindings resolve, and that you haven't declared duplicate edges. You find a disconnected node at build time, not when a message silently goes nowhere in production.

So the Go SDK has the full orchestration surface. What it doesn't have is a way to express that surface as a YAML file. Before we add one, we need to understand what we're compiling to, because the execution model has a sharp edge.

Under the hood: it's a superstep engine

Here's the part most people skip and then get bitten by. The Agent Framework doesn't just walk your graph node by node. It runs a "modified Pregel execution model, a Bulk Synchronous Parallel (BSP) approach with superstep-based processing." Pregel is the graph-processing model Google published in 2010 for computations over massive graphs, and BSP is the decades-older parallel-computing discipline it's built on. Borrowing it for agent workflows is a genuinely good call, and it changes how you reason about the graph.

Execution happens in discrete supersteps. Each one does the same five things:

Collect every message pending from the previous superstep.
Route each message to target executors based on the edges and their conditions.
Run all targeted executors concurrently.
Wait at a synchronization barrier for every one of them to finish.
Queue whatever new messages they emitted, and start the next superstep.

The barrier in step 4 is the whole game. Within a superstep, everything runs in parallel. Between supersteps, nothing does. The workflow will not advance until the slowest executor in the current step returns.

That barrier buys you three things that matter for production agents. Execution is deterministic: same input, same order, every time. Checkpointing is reliable, because a superstep boundary is a globally consistent snapshot, which is exactly why the SDK can save state and resume on a different machine. And reasoning is simpler, because within a step there are no races, every executor sees the same frozen view of messages.

Now the sharp edge. Say you fan out into two branches. One is a single long-running agent call, thirty seconds. The other is a quick three-step chain. You'd expect the quick chain to race ahead. It won't. Each step of that chain is its own superstep, and every superstep waits at the barrier for the thirty-second agent to finish. Your "fast" branch moves in lockstep with your slow one.

The docs are upfront about the fix, and it's counterintuitive the first time you read it: if you need two branches to run truly independently, don't make one of them a chain. Collapse its three steps into a single executor. Then both branches complete inside one superstep and neither blocks the other on intermediate boundaries. In a superstep engine, more nodes is not more parallelism. Sometimes it's less.

Building your own declarative layer in Go

Now the payoff. We want the declarative experience, a workflow described in YAML, running on Go. We're not going to reimplement PowerFx or bind .NET into our process. We'll build a small, honest engine: a fixed action vocabulary, simple ${var} interpolation instead of a formula language, and a pluggable agent interface so you can wire in agent-framework-go, the OpenAI SDK, or a fake for tests. It's the shape of the real thing at a size you can read in one sitting.

Start with the schema. A workflow is a name and a list of actions. Each action carries only the fields its kind needs, which in Go means one struct with omitempty fields and a Kind discriminator:

package flow

// Spec is the whole workflow, parsed from a YAML file.
type Spec struct {
    Name    string   `yaml:"name"`
    Actions []Action `yaml:"actions"`
}

// Action is one step. Only the fields relevant to its Kind are populated.
type Action struct {
    Kind  string   `yaml:"kind"`
    ID    string   `yaml:"id"`
    Var   string   `yaml:"var,omitempty"`
    Value string   `yaml:"value,omitempty"`
    Cond  *Cond    `yaml:"cond,omitempty"`
    Then  []Action `yaml:"then,omitempty"`
    Else  []Action `yaml:"else,omitempty"`
    Agent string   `yaml:"agent,omitempty"`
    Input string   `yaml:"input,omitempty"`
    Text  string   `yaml:"text,omitempty"`
}

// Cond is a deliberately tiny condition: does a variable equal a literal.
type Cond struct {
    Var    string `yaml:"var"`
    Equals string `yaml:"equals"`
}

That *Cond being a pointer matters: a nil Cond means the action isn't a conditional, which is cleaner than a zero-value struct you have to second-guess. This is the Go version of Microsoft's action vocabulary, trimmed to four kinds: set, if, agent, and send. Enough to be real, small enough to follow.

Next, state. Workflow variables and an output sink, with ${name} interpolation standing in for PowerFx expressions:

package flow

import "strings"

// State holds workflow variables and where output goes.
type State struct {
    Vars map[string]string
    Out  func(string)
}

func NewState(inputs map[string]string, out func(string)) *State {
    vars := make(map[string]string, len(inputs))
    for k, v := range inputs {
        vars[k] = v
    }
    return &State{Vars: vars, Out: out}
}

// interpolate expands ${var} references against the current variables.
func (s *State) interpolate(tpl string) string {
    out := tpl
    for name, val := range s.Vars {
        out = strings.ReplaceAll(out, "${"+name+"}", val)
    }
    return out
}

The agent is an interface, and that single decision is what makes this useful in a real project. The engine doesn't know or care what an agent is, only that you can hand it a prompt and get text back:

package flow

import "context"

// Agent is anything that turns a prompt into a reply. Wire in
// agent-framework-go, the OpenAI SDK, an HTTP call, or a fake in tests.
type Agent interface {
    Run(ctx context.Context, prompt string) (string, error)
}

Now the engine. It's a recursive walk over the action list, with a switch on Kind that mirrors the vocabulary. Every branch wraps its errors with enough context to name the failing action, because when a workflow blows up you want the step ID in the message, not a bare nil map panic three frames down:

package flow

import (
    "context"
    "fmt"
)

// Engine runs a Spec against a set of named agents.
type Engine struct {
    Agents map[string]Agent
}

func (e *Engine) Run(ctx context.Context, spec Spec, st *State) error {
    return e.runActions(ctx, spec.Actions, st)
}

func (e *Engine) runActions(ctx context.Context, actions []Action, st *State) error {
    for _, a := range actions {
        if err := e.runAction(ctx, a, st); err != nil {
            return fmt.Errorf("action %q (kind %s): %w", a.ID, a.Kind, err)
        }
    }
    return nil
}

func (e *Engine) runAction(ctx context.Context, a Action, st *State) error {
    switch a.Kind {
    case "set":
        st.Vars[a.Var] = st.interpolate(a.Value)

    case "send":
        st.Out(st.interpolate(a.Text))

    case "if":
        if a.Cond != nil && st.Vars[a.Cond.Var] == a.Cond.Equals {
            return e.runActions(ctx, a.Then, st)
        }
        return e.runActions(ctx, a.Else, st)

    case "agent":
        agent, ok := e.Agents[a.Agent]
        if !ok {
            return fmt.Errorf("no agent registered named %q", a.Agent)
        }
        reply, err := agent.Run(ctx, st.interpolate(a.Input))
        if err != nil {
            return fmt.Errorf("agent %q failed: %w", a.Agent, err)
        }
        if a.Var != "" {
            st.Vars[a.Var] = reply
        }

    default:
        return fmt.Errorf("unknown action kind %q", a.Kind)
    }
    return nil
}

Loading is the boring part, one os.ReadFile and one yaml.Unmarshal, both wrapped:

package flow

import (
    "fmt"
    "os"

    "gopkg.in/yaml.v3"
)

func Load(path string) (Spec, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return Spec{}, fmt.Errorf("read workflow %s: %w", path, err)
    }
    var spec Spec
    if err := yaml.Unmarshal(data, &spec); err != nil {
        return Spec{}, fmt.Errorf("parse workflow %s: %w", path, err)
    }
    return spec, nil
}

And here's a workflow that engine runs, a support router that's a straight port of the docs' own conditional-routing example, just in our smaller dialect:

name: support-router

actions:
  - kind: set
    id: capture_category
    var: category
    value: "${incoming_category}"

  - kind: if
    id: route
    cond:
      var: category
      equals: billing
    then:
      - kind: agent
        id: billing_agent
        agent: billing
        input: "Resolve this billing question: ${message}"
        var: reply
    else:
      - kind: agent
        id: general_agent
        agent: general
        input: "${message}"
        var: reply

  - kind: send
    id: reply_to_user
    text: "${reply}"

Wiring it together is a main that registers a couple of agents and runs the file. A fake agent stands in here so the example runs with zero credentials, and swapping it for a real one is a one-line change:

package main

import (
    "context"
    "fmt"
    "log"

    "example.com/flow"
)

// fakeAgent echoes a canned reply so the demo runs offline.
type fakeAgent struct{ name string }

func (f fakeAgent) Run(_ context.Context, prompt string) (string, error) {
    return fmt.Sprintf("[%s] handling: %s", f.name, prompt), nil
}

func main() {
    spec, err := flow.Load("support-router.yaml")
    if err != nil {
        log.Fatal(err)
    }

    engine := &flow.Engine{Agents: map[string]flow.Agent{
        "billing": fakeAgent{name: "billing"},
        "general": fakeAgent{name: "general"},
    }}

    st := flow.NewState(
        map[string]string{"incoming_category": "billing", "message": "I was double charged"},
        func(out string) { fmt.Println("OUT:", out) },
    )

    if err := engine.Run(context.Background(), spec, st); err != nil {
        log.Fatal(err)
    }
}

Run it and you get:

OUT: [billing] handling: Resolve this billing question: I was double charged

Change incoming_category to anything else and the same binary routes to the general agent, no recompile of the logic, because the logic lives in the YAML. That's the declarative property Microsoft is selling, running on Go, in code you fully own and can extend one case at a time.

Wiring it onto the real engine

The engine above walks the actions directly, which is perfect for getting started and fine for a lot of real workloads. But you lose what the superstep model gave you: deterministic parallelism, checkpointing, resumability, the built-in telemetry. When you want those, you don't throw the YAML away. You change the target. Instead of interpreting the actions, you compile them into an agent-framework-go graph, once, and let its runtime execute.

The mapping is direct. Each action becomes an executor. Sequential actions become AddEdge calls between them. An if becomes an AddSwitch with a case for the then branch and a default for the else. An agent action becomes an executor whose function calls your real provider. Sketched against the preview builder:

func Compile(spec flow.Spec, agents map[string]flow.Agent) (*workflow.Workflow, error) {
    nodes := make([]workflow.ExecutorBinding, 0, len(spec.Actions))

    for _, a := range spec.Actions {
        a := a // capture per iteration for the closure below
        switch a.Kind {
        case "agent":
            ex := workflow.NewExecutor(a.ID, func(input string) (string, error) {
                return agents[a.Agent].Run(context.Background(), input)
            }).Bind()
            nodes = append(nodes, ex)
        // set, if, send map to their own executors / switches...
        }
    }

    b := workflow.NewBuilder(nodes[0])
    for i := 0; i < len(nodes)-1; i++ {
        b = b.AddEdge(nodes[i], nodes[i+1])
    }
    return b.WithOutputFrom(nodes[len(nodes)-1]).Build()
}

That a := a line is load-bearing. Before Go 1.22 changed loop-variable scoping, capturing a in the closure without the shadow would give every executor the last action's values, the single most common bug when you build a slice of closures in a loop. On 1.22 and up it's redundant but harmless, and I'd still write it, because it says "this closure captures a per-iteration value" out loud to the next reader.

The point of this section isn't the exact builder calls, which are preview and will move. It's the architecture: one YAML dialect, two backends. A direct interpreter you own for the simple 80%, and a compile-to-agent-framework-go path for when you need the superstep guarantees. Your workflow files don't change when you switch. That's the real payoff of a declarative layer, and it holds whether Microsoft ships Go support next quarter or not. If they do, you migrate the compiler backend and keep your files. If they don't, you already shipped.

When this is actually worth building

Now the part the vendor tables won't tell you. Don't build any of this to avoid an if statement.

A declarative layer earns its keep under a specific condition: the people who need to change the workflow aren't the people who deploy the binary, and the workflow changes often enough that a redeploy per change is real friction. A support-routing flow that ops tweaks weekly, a content pipeline a PM reorders, an onboarding sequence that shifts with every partner deal. That's where moving the graph out of code and into a versioned YAML file pays for the engine you had to write. The file becomes the interface between the people who change the flow and the runtime that executes it.

If that's not your situation, a plain Go function is better than a YAML interpreter in every way that matters. It's type-checked, it's debuggable with a normal debugger, it's greppable, and it has no expression language to learn. Microsoft's own decision table says as much in its right-hand column: complex logic, maximum control, tight integration with existing code all point back to programmatic. The declarative version is worth it precisely and only when the constraint, a fixed vocabulary that a non-developer can safely edit, is the thing you want.

The Go SDK not having declarative workflows yet turns out to be a clarifying accident. It forces the question most teams skip on Python: do we actually need this, or does it just look tidy in a demo? If you need it, it's a hundred lines and you've now seen them. If you don't, you were always one well-named function away from the same result, and Go quietly kept you honest about it. Either way, you didn't have to wait for a pivot to fill in.

If you liked the "own your building blocks instead of importing a framework" flavor of this, the same instinct shows up in building a REST API in Go that's pleasant to extend, where Go 1.22's standard library removed most reasons to reach for a router.

Originally published at andriiboyko.com.

CQRS in NestJS: When It's Worth the Complexity

Andrii B. — Thu, 02 Jul 2026 14:16:38 +0000

The person most responsible for the industry-standard explanation of CQRS is also the person telling you not to use it. Martin Fowler's bliki entry on CQRS, the page half of the backend world links to when they explain the pattern, says plainly: "you should be very cautious about using CQRS." Not a hedge. Not a "consider the tradeoffs." A direct warning, from the guy whose writeup made the term mainstream.

That's not a contradiction. It's the actual state of the pattern: genuinely useful in a narrow set of cases, and a productivity tax everywhere else. The hard part isn't understanding CQRS. It's telling which side of that line your service is on.

What CQRS Separates

CQRS traces back further than most people assume. Bertrand Meyer's Command-Query Separation principle, from his work on Eiffel, said a method should either change state or return data, never both, at the level of a single function. CQRS takes that idea and moves it up a layer: instead of one function doing one thing, it's your write model and your read model that split. Udi Dahan was applying this to service-oriented systems as early as 2008, formalizing it as "Clarified CQRS" in 2009. Greg Young popularized the term and the modern shape of the pattern around 2010, usually alongside domain-driven design.

The core move: commands change state and return nothing meaningful. Queries return data and change nothing. Once you accept that split, you're free to give commands and queries completely different models, different validation rules, even different storage, because nothing has to reconcile a single "the truth" schema that serves both jobs at once.

The Read/Write Skew That Justifies It

Fowler names two legitimate reasons to reach for CQRS: a domain complex enough that a unified model would need to compromise for both directions, or a real performance requirement to scale reads and writes independently. Everything else is optional complexity dressed up as architecture.

The skew that matters isn't "we have more reads than writes." Almost every system does. It's a structural mismatch: your write side needs rich validation, business rules, and multi-step invariants, while your read side needs to answer questions your write model was never shaped to answer efficiently. A booking system that validates availability, conflicts, and cancellation policy on write, but needs to answer "show me every booking across three time zones grouped by room" on read, has structural skew. A blog with a posts table and a title/body/published_at doesn't, no matter how many more reads than writes it serves.

If your honest answer to "why can't the same model serve both" is "it could, we just don't want to write two queries," that's not skew. That's an excuse.

What the NestJS CQRS Module Gives You

@nestjs/cqrs gives you three buses: CommandBus, QueryBus, and EventBus. All three are built on RxJS Observables, so you can subscribe to the whole stream of commands, queries, or events flowing through your application, not just the individual handler results.

src/scheduling/commands/create-swap-request.handler.ts

@CommandHandler(CreateSwapRequestCommand)
export class CreateSwapRequestHandler
  implements ICommandHandler<CreateSwapRequestCommand>
{
  constructor(private readonly shifts: ShiftRepository) {}

  async execute(command: CreateSwapRequestCommand): Promise<string> {
    const shift = await this.shifts.findById(command.shiftId);
    shift.requestSwap(command.requestedBy, command.reason);
    await this.shifts.save(shift);
    return shift.id;
  }
}

The command handler owns validation and business rules. It doesn't return the shift, a DTO, or anything the frontend would render, just enough to confirm the write happened. A matching query handler pulls from whatever shape is fastest to read, which does not have to be the same tables the command touched.

One detail that catches people off guard: CommandBus, QueryBus, and EventBus are singletons, so combining them with NestJS's request-scoped providers takes extra care. The library handles this by spinning up a new instance of a request-scoped handler for each command, query, or event it processes, rather than sharing one instance across requests. It works, but it's not obvious from the decorator syntax that anything special is happening underneath.

Event handlers run asynchronously and are expected to handle their own exceptions. An event handler that throws doesn't crash the request that published the event, it gets caught, wrapped into an UnhandledExceptionInfo, and pushed onto a separate UnhandledExceptionBus stream.

If nothing is listening to that stream, the failure disappears silently. First time I saw this, I assumed a failing event handler would at least log something by default. It doesn't. You have to wire that up yourself.

CQRS Is Not Event Sourcing

These two get bundled together constantly, partly because they show up in the same tutorials and partly because event sourcing naturally produces a write side and a read side that already look like CQRS. But they're independent decisions.

Event sourcing means your source of truth is an append-only log of events, and current state is a projection computed by replaying them. CQRS means your read and write models are separate. You can event-source without CQRS (replay events into the same model you write through). You can do CQRS without event sourcing (a normal relational write model, plus a denormalized read table kept in sync by a projector). NestJS's CQRS module happens to ship with AggregateRoot and event-emitting building blocks that make it easy to slide into event sourcing, but nothing about CommandBus and QueryBus requires it.

Conflating the two is how projects end up with the operational cost of an event store (replay logic, event versioning, snapshotting) when all they actually needed was a read-optimized table.

The Failure Mode: Applying CQRS to Everything

The most common way teams burn the investment is treating CQRS as a system-wide default instead of a targeted tool. Fowler's own framing: many systems fit a CRUD mental model just fine, and forcing CQRS onto them is "a significant mental leap for all concerned" with no matching payoff.

The failure compounds in a microservices context. If you don't identify your aggregate boundaries correctly first, and then apply CQRS on top of that mistake, you end up splitting a single aggregate's data across services, because the read side "needs" a view that spans what should have been one consistency boundary. That's not CQRS creating the mess, it's CQRS making an existing modeling mistake more expensive to carry.

The rule that scales: apply CQRS to the specific bounded contexts where the skew is real, never to a whole application by default. A platform can have three services where CQRS earns its keep and twelve where a repository and a DTO are all anyone needed.

The Eventual Consistency Tax You're Paying

Splitting the models means the read side can lag the write side. How much depends entirely on your projection mechanism, synchronous in the same transaction, asynchronous via a message queue, or somewhere in between, but the lag is never exactly zero once the models are meaningfully separate.

The concrete version of this problem: a user places an order, and it can take anywhere from a couple of seconds to a couple of minutes before that order shows up in their order history, depending on how the projection pipeline is built. That's not a bug. It's the actual cost of the pattern, and it has to be a product decision, not something the write side discovers by accident when a support ticket comes in asking why a booking "disappeared."

If your UI can't tolerate that lag anywhere in the flow, either the projection needs to be synchronous for that specific path, defeating some of the scaling benefit, or CQRS is the wrong tool for that particular read.

Where I'd Reach for This

On the healthcare platform I work on now, the scheduling side has exactly this shape: writing a shift change means checking coverage rules, skill-level requirements, and conflict windows across a rotation, real domain complexity on the command side, while the read side mostly needs to answer "show me the week" in a dozen different groupings (by provider, by department, by shift type) fast enough for a calendar UI that gets hit constantly. That's read/write skew, not a preference.

Credentialing, on the same platform, mostly isn't. A verification record has a status, an expiration date, and an audit trail. The queries against it are close enough to the write shape that splitting the models would add a synchronization problem without buying anything back. One service, two very different answers to "should this use CQRS," and the difference is the skew, not the domain's importance.

That's the actual decision procedure: not "is this domain important" or "are we doing microservices," but "would the read model and the write model genuinely want to be different shapes, and is the eventual-consistency cost something the product can absorb." If both answers are yes, the complexity Fowler warns about is the complexity you're supposed to be paying for.

Originally published at andriiboyko.com.

Bounded Contexts in a Real Codebase, Not a Diagram

Andrii B. — Thu, 02 Jul 2026 14:16:24 +0000

Why the one-context-one-service rule breaks down once you map real domain boundaries onto a live platform, and what decides where the seams go instead.

Everyone draws the same diagram. A box for each part of the domain, a straight line from each box to a service, one arrow per box. It's the tidiest picture you'll ever ship in an architecture review, and the moment you try to build it exactly as drawn, it starts to lie to you.

I've now been on both sides of that diagram: the person who drew it with total confidence in year one, and the person who had to explain eighteen months later why the "Credentialing" box didn't match the credentialing service. The mismatch wasn't a mistake. It's what happens when you take a modeling concept and treat it like a deployment topology.

What a Bounded Context Is

The term comes from Eric Evans's 2003 book Domain-Driven Design: Tackling Complexity in the Heart of Software. A bounded context is the boundary inside which a particular model, and the language that describes it, stays consistent. Outside that boundary, the same word can mean something else entirely, and that's fine, because you're no longer inside the model where it was defined.

The canonical example: "Customer" in a sales context means someone who can place an order. "Customer" in a support context means someone with a ticket history and an SLA. Same word, two different models, two different sets of rules about what's valid. A bounded context is where you stop pretending those are the same thing and give each one its own vocabulary, its own invariants, and its own boundary.

That's a modeling concept. It says nothing about how many services you run, how you deploy them, or who's on call for which one. Which is exactly where the diagram goes wrong.

The One-to-One Assumption, and Why It Breaks

The popular shorthand is: one bounded context, one microservice. It's easy to teach, easy to draw, and easy to sell in a slide deck. DDD writer Vlad Khononov put the actual relationship more precisely: "A Microservice is a Bounded Context, but not vice versa. Not every Bounded Context is a Microservice." A bounded context defines the largest boundary inside which a model can stay consistent. A microservice is a deployment decision made inside that boundary, and sometimes below it, not a mirror of it.

Here's the failure mode in practice. A team draws contexts too small, one per entity, and ends up with a dozen services that all have to call each other synchronously to do anything useful. That's not microservices. That's a monolith with the process boundaries moved into the network, which is strictly worse: same coupling, new latency, new failure modes.

The industry has a name for it now: the distributed monolith. It shows up most often when a team splits a system along its existing code layers (controllers, services, repositories) instead of along real domain boundaries, then calls the result "microservices" because there are multiple deployables.

The opposite mistake is just as common and less talked about: drawing one context for the entire domain, then building a single service with DDD vocabulary sprinkled over what is, underneath, still a big ball of mud. You get the ceremony of bounded contexts (aggregates, repositories, a ubiquitous language doc nobody updates) without the actual isolation that makes any of it worth doing.

The honest answer is that a bounded context and a service are two different kinds of boundary, and they only sometimes line up:

One bounded context can span multiple services, when the context is large enough that splitting it makes operational sense (different scaling needs, different release cadence, different team).
Multiple small, tightly related contexts can live inside one service, when splitting them would only add network calls without adding independence.
A context can be split across a synchronous API and an asynchronous event stream, which is not "two contexts," it's one context with two integration surfaces.

Deciding which of these is true for a given part of your domain depends on things a bounded context diagram can't tell you: team size, deployment cadence, scaling profile, and how often the boundary needs to move.

Where a Real Split Came From

I've spent the last year leading the technical direction of a healthcare workforce platform built around two products: a staff scheduling system and a credentialing system. On paper, that's two bounded contexts and, if you followed the popular rule, two services. In practice, the platform runs scheduling, credentialing, and integrations as separate services, and that third one is the interesting part.

Integrations wasn't its own bounded context in the domain sense. It doesn't own a piece of business vocabulary the way scheduling ("shift," "coverage," "swap request") or credentialing ("primary source verification," "expiration," "attestation") do. What it owns is a boundary problem: every external system we talk to (identity providers, document verification vendors, notification services) has its own model, its own failure modes, and its own pace of change, and none of that should leak into the scheduling or credentialing models.

That's the anti-corruption layer pattern from context mapping, given its own service instead of a library everyone imports. Once external integrations lived behind their own boundary, the scheduling and credentialing services stopped needing to know anything about a specific vendor's API shape, retry semantics, or auth flow. They call an internal contract; the integrations service is the only thing that has to change when a vendor changes theirs.

That's a service boundary that exists for operational reasons (isolate volatility, isolate failure, let one team own vendor relationships) layered on top of a modeling boundary that exists for domain reasons (keep "shift" and "verification" from ever meaning two things at once). Stabilizing the platform's architecture meant getting that distinction right, not drawing a cleaner box diagram.

When One Service Should Hold Multiple Contexts

The reverse case matters just as much, and it's the one people are more reluctant to admit out loud: sometimes the right call is to keep two related contexts in the same service, at least for a while.

Two sub-domains that change together, get deployed together, and are owned by the same two-person team don't need a network boundary between them. Splitting them early buys you nothing except a second CI pipeline, a second on-call rotation to staff, and a synchronous call where a function call used to be. The tradeoff to weigh isn't "is this technically a separate context," it's "does separating this reduce coordination cost, or just add infrastructure?"

Signals that it's still too early to split:

The two contexts are always deployed in the same release.
One team owns both, and that's not changing soon.
The only reason for the split is "microservices are the right architecture," not a concrete scaling or ownership problem.

Signals that it's worth the network hop:

The contexts have genuinely different scaling profiles (one is read-heavy and cacheable, the other is write-heavy and transactional).
Different teams need to own them, and shared deployment is actively slowing both down.
One context's failure shouldn't be able to take the other down, and today it can.

None of these are visible on a static bounded-context diagram. They're operational facts about the system you're running right now, and they change over time, which is why context boundaries and service boundaries are allowed to diverge and then re-converge later.

The Seams: Context Mapping Patterns Worth Knowing

Once you accept that contexts and services don't automatically line up, the interesting question becomes: what sits at the seam? DDD's context mapping patterns answer that, and three of them cover most real cases.

Shared kernel is when two contexts agree to share a small, explicitly maintained subset of the model, usually because splitting it would cost more than the coordination overhead of keeping it in sync. It's the pattern to reach for rarely and deliberately, not the default.

Customer/supplier is when one context's team can influence the other's roadmap because they depend on it, and the supplier team treats that dependency as a real constraint on what they ship. This is a people pattern as much as a code pattern: it only works if the supplier team honors it in practice.

Anti-corruption layer is the one that shows up the most in practice, and it's the pattern the integrations service above is built on. A translation boundary sits between two models so that neither one has to bend to accommodate the other. A small TypeScript sketch of the shape:

src/integrations/verification/anti-corruption-layer.ts

// The vendor's shape. We don't control this and it can change without warning.
type VendorVerificationResponse = {
  verification_status_code: "V1" | "V2" | "V3";
  subject_ref: string;
  checked_at_utc: string;
};

// Our domain's shape. This is the only thing Credentialing ever sees.
type PrimarySourceVerification = {
  status: "pending" | "verified" | "failed";
  providerId: string;
  verifiedAt: Date | null;
};

function translate(vendorResponse: VendorVerificationResponse): PrimarySourceVerification {
  const statusMap: Record<VendorVerificationResponse["verification_status_code"], PrimarySourceVerification["status"]> = {
    V1: "pending",
    V2: "verified",
    V3: "failed",
  };

  return {
    status: statusMap[vendorResponse.verification_status_code],
    providerId: vendorResponse.subject_ref,
    verifiedAt: vendorResponse.verification_status_code === "V2" ? new Date(vendorResponse.checked_at_utc) : null,
  };
}

Nothing clever is happening here on purpose. That's the point: the translation function is the entire cost of keeping the vendor's model out of the domain. When the vendor renames a field or adds a fourth status code, this function is the only place that changes.

Finding the Boundaries Before You Build Anything

If you're doing this for the first time, don't start by drawing boxes. Start with event storming: get the people who understand the domain in a room (or a shared board), and map out the significant business events on a timeline, in the language the business uses for them, not the language your database schema uses. Boundaries tend to reveal themselves as clusters: events that trigger each other tightly belong together, and gaps where one cluster hands off to another, often with a change in vocabulary, are your candidate context boundaries.

It's slower than opening a whiteboard and drawing four boxes from memory. It's also the difference between a boundary that reflects how the business actually works and a boundary that reflects how the code happened to be organized when you looked at it.

Where the Boundary Should Have Been

If I were drawing that diagram again for the platform I'm working on now, I wouldn't add a fourth box for "Integrations" as if it were a peer domain concept next to scheduling and credentialing. I'd draw it as what it is: an anti-corruption layer that earned its own deployable because of operational concerns, not because the domain model demanded a third bounded context. The distinction matters, because the next time someone asks "should this be its own service," the domain diagram won't answer the question. The operational tradeoffs will.

Originally published at andriiboyko.com.