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 SEQUENCEUnderstand how the ideas connect
Choose a point to look closer ↓
01 / Guide section
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.
Read the supporting context ＋
Write down the behavior callers depend on before changing the boundary: accepted inputs, returned data, error cases, authorization and externally visible effects. This is your compatibility checklist.
Explore a section, then continue with the complete article below.
1 / 4
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.
Write down the behavior callers depend on before changing the boundary: accepted inputs, returned data, error cases, authorization and externally visible effects. This is your compatibility checklist.
Existing concern
ContractSpec responsibility
Application responsibility
Request shape
Describe and validate the operation input
Map the existing request into that shape
Business logic
Bind the operation to a handler
Keep the implementation and domain invariants
Identity and permissions
Carry requirements and decision context
Authenticate the caller and provide trusted policy decisions
HTTP behavior
Project through a chosen adapter
Preserve intended routes, status semantics and clients
◇Choose an evaluation that can teach you something.Explore a situation · 3 ways to look closer＋
Keep the existing application. Make one operation explicit, then decide what the next useful proof would be.
Which situation sounds closest?
A CONCRETE SITUATION
Start with behavior you can compare.
An existing account lookup already returns a useful result to an API consumer.
What changes
The operation gains an explicit input, result, errors and ownership boundary.
What stays explicit
Its business implementation can remain in place.
FOLLOW THE CONSEQUENCE
Compare the current route with the new binding using the same valid and invalid cases. Widen the scope only after the difference is understood.
Define a contract that reflects the behavior you intend to support. Bind the existing service function through a small handler rather than moving the entire service into the contract declaration. Make input and output translations explicit.
Register the exact contract version and attach the handler to that registration. A declaration without a bound handler is discoverable information, not a runnable operation. Keep database clients and provider secrets in host-owned code.
Compare at the boundary
Run the same representative requests against the old boundary and the new one in a disposable environment. Compare meaningful values and failures rather than incidental timestamps. Include a denied or malformed request and prove it cannot invoke the protected effect.
When transport names or response envelopes change, treat the difference as an API change. Add a deliberate compatibility mapping or update consumers together; do not assume shared types preserve a wire protocol.
Expand when the first seam pays off
A useful next step is a second interface to the same registered behavior, such as a human form and an MCP tool. You can then see which rules stopped being duplicated and which responsibilities remain in the host.
Importer output can help inventory a larger system, but inferred contracts still need review. Existing code can reveal shape and routing while missing the business reason for a policy or the scope of an approval. Make those decisions explicit before expanding.
See it in an example.
Contracts / Beginner
Write your first contract
Define an operation
Follow user.create from an email schema to a typed handler. Start with the smallest maintained example.
01
Describe the input
02
Name the operation
03
Follow the handler
Source demonstratesThe maintained source declares user.create with a required email input and a typed output.
Does not demonstrateA database account is created or an email is sent.
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＋
Source demonstrates
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.
Does not demonstrate
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.
Look inside the guideOpening context · complete reading path＋
What this walkthrough demonstrates
The maintained minimal example declares an operation named user.create. It accepts an email and returns the same email. Despite the operation's name, the shown handler does not create a persistent account, send a message or call a provider.
Look inside the guideOpening context · complete reading path＋
Start from one registry
Register the operation and bind its handler once. The REST createFetchHandler and MCP registerMcpTools implementations both call OperationSpecRegistry.executeResult. That shared invocation path is the useful connection between an API request and an agent tool call.
Look inside the guideOpening context · complete reading path＋
Give each test one question
An operation has several boundaries, and one green check cannot answer every question about them. Separate declaration validity, business behavior, adapter behavior and external consumption so failures tell you where to look.
