Skip to content
ContractSpec
Start here

Core guide · Concepts · 3 min read

Contracts, handlers and adapters

Understand the separate responsibilities that let one operation serve several interfaces.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

The contract describes the behavior

An operation contract names a command or query and describes its data and requirements. The model includes metadata, input and output schemas, result definitions, policy, declared effects, transport hints and links to related presentations or tests.

A declaration is useful before it executes: another engineer can inspect its purpose and a tool can discover its shape. But an operation description is not a database implementation, and a policy field is not itself a trusted authorization decision.

1 / 4

0 points in your packet

The contract describes the behavior

An operation contract names a command or query and describes its data and requirements. The model includes metadata, input and output schemas, result definitions, policy, declared effects, transport hints and links to related presentations or tests.

A declaration is useful before it executes: another engineer can inspect its purpose and a tool can discover its shape. But an operation description is not a database implementation, and a policy field is not itself a trusted authorization decision.

The handler performs the work

A handler is the application function bound to a registered operation. It reads or changes the resources your product owns and returns a result that the runtime can validate. It can use host-provided dependencies without putting those providers into the portable declaration.

Business invariants remain your responsibility. A valid input might still refer to an unavailable resource or request a transition the product does not allow. Model those outcomes deliberately and test them in the handler.

The adapter translates an interface

Adapters connect transport-specific requests to the registry. REST handles HTTP input and responses; MCP registers tool shapes and returns tool results. They can call the same operation without having identical wire formats.

The host constructs the context behind those adapters. It establishes identity, binds policy and approval ports, and supplies persistence or provider implementations. Keeping that setup explicit is what lets the contract stay portable.

LayerOwnsDoes not imply
ContractMeaning, shape and declared requirementsAn implemented or authorized effect
Registry and runtimeBinding, common execution and result handlingA production identity system or database
HandlerBusiness implementationAutomatic correctness from its type
AdapterHTTP, MCP or other interface projectionIdentical transport semantics
HostTrusted context and concrete dependenciesAuthority from a browser-supplied role string

Follow a change through the layers

Suppose an export now requires a reason. The contract gains a required input field, callers must provide it, and the handler decides how that reason is used or recorded. Runtime validation can reject an old request shape, while a migration determines whether older consumers remain supported.

This makes a change easier to review: the declaration exposes the intended boundary, and the implementation diff shows the business consequence.

A change has an owner and a set of consequences.

A report export now needs a reason. Follow the change through authored meaning, derived output and a caller that still uses the old input.

Which part are you changing?

A CONCRETE SITUATION

The requirement becomes part of declared behavior.

A required reason is added to the operation input.

01 / Author

Change the declaration that owns the required input.

What changes

Callers must now supply the new field for that contract version.

What stays explicit

The handler still decides how the reason affects the business work.

Follow the consequence

Plan compatibility for existing consumers. A required input can be a behavioral break even if the handler’s main implementation is unchanged.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.