Docs · The doctrine · Section 02
The decoupling that makes language and topology secondary
Before discussing language and deployment, one must understand why these choices become secondary. Two boundaries suffice: the domain's ports, and a standardized integration protocol between processes.
Boundary 1, the domain's ports
The domain expresses its needs as contracts (ports): provide a model generation, persist state, execute an action, read a source. Each contract is implemented by an adapter. The adapter can be written in any language as long as it honors the contract. Language becomes an adapter implementation detail. This decoupling has a name, hexagonal architecture, or "ports and adapters", formalized by Alistair Cockburn in 2005. Applying it to the model itself, treated as one adapter among others, is an idea the ecosystem increasingly shares; what follows claims no paternity over it, but pushes it through to its consequences, from evaluation to memory, from security to contract governance.
This last idea deserves to be pushed all the way, because it grounds the durability of the whole edifice. The engine placed behind the model port is bound only by its contract, not by its nature. Today it is a language model; tomorrow it could be a reasoning engine of another kind, and the architecture would survive it without a rewrite, as long as it honors the same contract. What would then remain to address is not the boundary but the engine's properties: as long as it reasons non-deterministically over open inputs, the evaluation, memory, and security requirements described further on hold identically. In other words, the model is not the center the architecture organizes, it is a component the architecture can replace, down to its paradigm. Let us be fair, however, about the everyday benefit of this boundary: it lies less in the actual replacement of the model, rarer than commonly claimed, than in the ability to test and reason about the domain without depending on the model. Substitutability is the insurance kept in reserve; testability is the everyday dividend. And one clarification that holds for everything else: the port is clean for the typed contract, but the behavioral boundary is not guaranteed by the type, it is validated (Section 12).
Boundary 2, the integration protocol between processes
When a capability lives in another process, even another language, it is exposed through a standardized tool protocol. The system consumes that process as a tool provider, and exposes its own use cases the same way. The cross-language boundary is sharp and stable.
Diagram, language and topology behind the contracts
Practical consequence
The debate between full TypeScript and a Python, Rust, or Go back end ceases to be an architecture dilemma. It is a local tradeoff, made adapter by adapter, according to the ecosystem of the capability concerned. The same reasoning applies to splitting into services: a service is an adapter that has migrated into its own process, without the domain changing.
The contract, beyond the type
A contract is not reducible to a typed schema: it is governed, it carries meaning, and it must come to terms with what already exists. Three facets of a single requirement.
It is governed. A stable contract is not a frozen contract. Every contract, domain port, exchanged message, or persistence schema, evolves; without discipline it drifts and silently breaks its consumers, the classic ailment of service-oriented architectures. Four rules govern it. It carries a version. Its evolution is additive by default, and the consumer is a tolerant reader: it ignores what it does not know and accepts the absence of an optional field, which makes additions non-breaking. A genuinely breaking change is not made in one block, but in two steps, expand and contract: introduce the new, migrate the consumers, remove the old once no one uses it anymore. Finally, provenance, which already recorded what a prompt saw and what memory supplied, extends to contracts and events: knowing who produces, who consumes, and under which version makes it possible to measure the impact of a change before making it. Verification, for its part, belongs to the consumer (Section 12): it expresses its expectations as an executable contract, and a producer change that would break them fails at integration, before reaching production.
Messages and events that cross a boundary carry a stable envelope, separate from their payload: an identity, a qualified type, a schema reference, a timestamp, an origin. This taxonomy is what lets a consumer route, filter, and trace without knowing the producer's details.
It carries meaning. A contract honored in form can still denote different things. "Customer", "account", "commitment", "validation" do not mean the same thing from one system to the next, nor from one agent to the next. The hard part of interoperability is not "how do we call each other" but "are we talking about the same thing". The answer is not a central data model that would say everything for everyone: such a model quickly becomes unmanageable, slow to evolve, and ends up bypassed. It is, per context, an explicit shared language, the one the business and the code share, sharp boundaries between contexts, and a minimal shared vocabulary at the seams only. The adapter plays its second role there: beyond translating a protocol, it aligns meaning, exactly as the anticorruption layer translates the dialect of a legacy system. This alignment counts doubly for an agentic system: absent fixed semantics, a model will force neighboring but distinct concepts together and invent false correspondences. The semantic contract is, against these hallucinated alignments, what the typed schema is against malformed data.
It comes to terms with the existing. On greenfield, the port is a sharp boundary and the adapter is thin. On an existing system, the boundary is not given: its contracts are implicit, its semantics undocumented. The adapter then becomes an anticorruption layer that translates the legacy system's dialect into the domain's language and keeps the old model from contaminating the new. Moving off an existing system is done by progressive replacement, feature by feature, never in a single stroke. It must be said plainly: the ports and adapters model holds best on greenfield; on legacy estate it still holds, but the adapter pays for an explicit translation, and that is where the real cost of integration concentrates. Isolation is precisely what makes that integration clean, provided one never pretends the boundary is free.