EXAMPLE / Contracts
Write your first contract
Follow user.create from an email schema to a typed handler. Start with the smallest maintained example.
Follow the pattern. Inspect its limits.
Explore the source walkthrough, its evidence and the choices you would make in your own application.
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.
An exploration of the inspected source; no example is executed here.
The situation.
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.
What you will learn
- Give an operation a stable key and version.
- Describe the accepted input and returned output in the same contract.
- Connect a typed handler without assuming the metadata implements the business operation.
Start with a required input.
This form illustrates an email-shaped input and echo result. It does not run ContractSpec’s schema library or create an account.
Follow the operation.
- 01
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.
- 02
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.
- 03
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.
- 04
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 the 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.
What it does not establish.
- 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.
Bring it into your environment.
Use the exact source context and prerequisites below. A source walkthrough is not a verified public-package installation recipe.
- Access to the inspected source repository and a checkout at the cited revision.
- The repository's Bun workspace dependencies and required generated package exports. These instructions were inspected; the examples were not executed in this review.
Working directory: examples/minimal
bun run smoke
bun run validateThe smoke fixture checks metadata and feature wiring; validation checks the contract. Neither is an account-creation integration test.
Commands and source inspected; not executed here.
Read the related guide →Make the pattern your own.
- Keep the operation key and version intentional as behavior changes.
- Add persistence in a handler or port with explicit tests.
- Use the approval fixture or draft-and-send story when learning governed writes.
Inspect the evidence.
Reviewed 2026-10-27 · b67c376f
Pinned source links require repository access; publication and anonymous package availability were not checked for this example.
- Declared maturity
- stable
- Catalogue registration
- Registered
- Inline preview
- No generated inline UI preview registered
- Execution in this review
- Not rerun
- Production qualification
- Not assessed