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.
⌘↗
SÉQUENCE DE LECTUREComprendre les liens entre les idées
Choose a point to look closer ↓
01 / Section du guide
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.
Lire le contexte à l’appui ＋
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.
Explore a section, then continue with the complete article below.
1 / 4
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.
Couche
Owns
Does not imply
Contract
Meaning, shape and declared requirements
An implemented or authorized effect
Registry and runtime
Binding, common execution and result handling
A production identity system or database
Handler
Business implementation
Automatic correctness from its type
Adapter
HTTP, MCP or other interface projection
Identical transport semantics
Host
Trusted context and concrete dependencies
Authority 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.Trace the mechanism · 3 ways to look closer＋
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?
UNE SITUATION CONCRÈTE
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.
Ce qui change
Callers must now supply the new field for that contract version.
Ce qui reste explicite
The handler still decides how the reason affects the business work.
SUIVRE LA CONSÉQUENCE
Plan compatibility for existing consumers. A required input can be a behavioral break even if the handler’s main implementation is unchanged.
Inspect the walkthroughBehavior · proof and limits · source checks＋
Follow the source behavior
A small user.create command accepts one required email address. Its current handler returns the same email. This gives you a compact place to understand the contract and handler boundary before adding storage or authentication.
Describe the input
Read UserInput in src/contracts/user.ts. The schema has one required EmailAddress field. The command uses the schema for both input and output.
Name the operation
Inspect the user.create key, version 1.0.0, owner, goal, and anonymous authentication policy. These describe the operation and its boundary.
Follow the handler
Open src/handlers/user-input.handler.ts. HandlerForOperationSpec derives the handler shape from CreateUser. The implementation returns input.email; it does not create a persisted account.
Inspect and adapt the starter
Read the package smoke fixture and validation script. Replace the echo handler with your own behavior, then test that behavior and the contract boundary together.
What this example establishes＋
Ce que montre la source
The maintained source declares user.create with a required email input and a typed output.
The handler is typed from the operation specification.
A source smoke fixture checks starter metadata and feature registration.
Ne démontre pas
A database account is created or an email is sent.
This example exposes an MCP tool: its manifest disables MCP.
This starter implements an approval gate, persistence, or production authentication.
Inspect the walkthroughBehavior · proof and limits · source checks＋
Follow the source behavior
A reference agent drafts a message, waits for approval, and invokes sendMessage. The MCP smoke test uses a real MCP server and client over an in-memory transport. The actual handlers remain deterministic fixture logic.
Separate the two operations
The source defines draftAndSend.draftMessage and draftAndSend.sendMessage. Drafting is automation-safe; sending declares its approval requirement.
Inspect the workflow
The example connects draft, approval wait, send, and receipt stages through the WorkflowDevkit adapter. This is a composed reference flow, not an invitation feature in the minimal starter.
Inspect the MCP boundary
The smoke test registers the operation registry as MCP tools, then calls sendMessage with valid, absent, and tampered receipt evidence. It expects success only for the valid case.
Read what send actually does
The bound handler derives a message ID and returns status sent in memory. To send through a real provider, supply your own port and preserve the same execution boundary.
What this example establishes＋
Ce que montre la source
The source smoke fixture drives a real MCP server/client over linked in-memory transports.
The fixture asserts APPROVAL_REQUIRED for missing and tampered receipts.
The same registry gate is used by the MCP adapter rather than a second hand-written approval path.
Ne démontre pas
Delivery of a Slack message, email, invitation, or other network request.
A fresh successful run or production human approval system.
That the minimal example includes MCP; this is a separate source package.
Look inside the guideOpening context · complete reading path＋
Follow the execution boundary
A registered call resolves an operation and its bound handler, prepares the input and execution context, invokes the handler, and validates the returned value. The exact checks depend on the contract and the ports supplied by the host.
Look inside the guideOpening context · complete reading path＋
Select a small adoption seam
Choose a function or endpoint that already has a clear owner and useful tests. Prefer a contained read or a reversible local action for your first exercise. A workflow that spans several providers, jobs and billing decisions makes it difficult to tell whether a problem comes from your application or the integration.
Look inside the guideOpening context · complete reading path＋
Describe what the caller must supply
An input schema should express the shape you actually accept, including required values and constraints that can be checked before execution. Keep the distinction between an absent value and a valid empty value clear.
