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
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.
Read the supporting context ＋
OperationSpec separates the main input from optional transport-related parameter, query and header models. Inspect the adapter's mapping before assuming a field is read from a particular part of a request.
Explore a section, then continue with the complete article below.
1 / 4
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.
OperationSpec separates the main input from optional transport-related parameter, query and header models. Inspect the adapter's mapping before assuming a field is read from a particular part of a request.
Describe what the caller may rely on
The output model tells callers what a successful handler must return. Use a stable shape that reflects the product outcome rather than leaking the entire response from a provider.
Output validation detects a mismatch after the handler returns. It helps identify a broken boundary, but the host still owns the transaction or recovery behavior of effects that have already happened.
◉Choose the check that answers the question.Examine the support · 3 ways to look closer＋
One green check cannot establish every boundary. Connect the intended claim with the smallest observation that can support it.
What do you need to establish?
A CLAIM TO EXAMINE
Observe a denied call through the real entry point.
The operation explicitly requires approval, and the request otherwise has valid input.
What it supports
A disposable counter or fake outbox can reveal whether the handler was entered.
What it leaves open
A hidden button or mocked always-allow verifier cannot establish the guard.
WHAT WOULD HELP YOU DECIDE
Omit the required receipt, inspect the adapter’s canonical failure and verify the effect remains untouched in your actual test.
The model supports typed success and failure catalogs as well as compatibility error declarations. Use expected failures to describe product cases that a caller can handle, such as unavailable resources or a rejected transition.
The registry's executeResult path carries a canonical result and normalizes failures with operation and trace context. Adapters project that result into their own protocol. Avoid making clients inspect an incidental human error string as their primary control flow.
Kind of outcome
Caller concern
Where to investigate
Invalid request
Correct the submitted data
Input schema and mapping
Expected business failure
Choose another valid product action
Declared result and handler
Denied execution
Satisfy an authorized policy or approval path
Host decision context
Invalid handler output
Report or repair an implementation defect
Handler and output model
Use examples as boundary fixtures
Keep a representative input and result near the operation and use them in the guide and the test. Include one failure case that demonstrates the reason the constraint exists.
When you change a required field or named outcome, review clients and docs together. Matching TypeScript imports alone does not show whether a deployed caller still sends the old wire shape.
See it in an example.
UI / Intermediate
Capture now, complete when ready
Build an interface
Use form contracts to accept a minimal intake while keeping missing readiness fields visible.
01
Choose the form contract
02
Inspect minimal intake
03
Inspect conditional validation
Source demonstratesThe inspected fixture separates acceptance from completion status.
Does not demonstrateProduction form storage, submission delivery, or authentication.
Inspect the walkthroughBehavior · proof and limits · source checks＋
Follow the source behavior
A customer intake can begin with a name. In the fixture, a quick capture is accepted while email, phone, and consent remain completion debt. A richer profile can then determine whether the record is ready for the next workflow.
Choose the form contract
Inspect all-fields, progressive-steps, and customer-projection forms. The package includes field kinds, conditional rules, sections, and step layouts.
Inspect minimal intake
The quick-capture fixture contains a customer ID and display name. The smoke test expects capture to succeed and completion to remain incomplete with email, phone, and consent debt.
Inspect conditional validation
Another test builds Zod validation with relations and expects a missing repeated contact value to be reported at contacts[0].value.
Use the public proof map
The proof-config export lists docs, sandbox, forms, and UI entrypoints. Adapt through the supported exports, then supply your own persistence and submission behavior.
What this example establishes＋
Source demonstrates
The inspected fixture separates acceptance from completion status.
The source tests inspect field coverage, step layout, conditional validation, and public exports.
The public preview is deterministic fixture state with no required backend or credentials.
Does not demonstrate
Production form storage, submission delivery, or authentication.
A production renderer for every host application.
A PII hint automatically implementing a privacy control.
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.
