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
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.
Read the supporting context ＋
For a first integration, keep the matrix small. Choose the success case your tutorial promises and the failure that demonstrates its most important protection.
Explore a section, then continue with the complete article below.
1 / 4
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.
For a first integration, keep the matrix small. Choose the success case your tutorial promises and the failure that demonstrates its most important protection.
Check
Question it answers
Useful assertion
Contract/schema
Does the declared shape behave as intended?
Required values accepted or rejected
Handler
Does the business rule hold?
Expected state transition and outcome
Registry
Does configured execution enforce the boundary?
Denied request leaves handler count at zero
Transport
Does the actual API/tool expose it correctly?
Wire result and context mapping
Consumer
Can users install and import this version?
Clean external project succeeds
◉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.
Use a handler with a visible disposable effect, such as a local counter or fake outbox. Supply otherwise valid input so the request reaches the guard you are testing. Missing approval should leave that effect untouched.
Invoke the adapter used by your users, not only a private helper. For an API-plus-MCP claim, exercise both real entry points and inspect their canonical failure information.
Test the risks of your implementation
A schema can validate input while a handler still produces the wrong state. Add tests for business invariants, resource ownership and the failure paths of any provider you bind. Verify idempotency or retry behavior where your application depends on it.
An invalid output is detected after handler execution. If an effect must be atomic with a record of the result, test the host's transaction or outbox implementation rather than assuming output validation supplies rollback.
Report the scope of the result
Repository tests use the repository's dependency graph. Packed-artifact checks test built tarballs. An anonymous registry consumer verifies that an external user can fetch and execute the published version. Keep these results separate.
For documentation, record the source or package version and exact scenario. A metadata smoke test is useful for an example catalogue, but it should not be described as a successful end-to-end workflow.
See it in an example.
Execution / Intermediate
Stop a write before it runs
Control side effects
Trace a REST request through an approval gate and inspect the zero-handler-call denial assertion.
01
Declare the boundary
02
Inspect the denied request
03
Inspect the approved request
Source demonstratesThe inspected denial test asserts that the handler is not invoked when a required receipt is missing.
Does not demonstrateA fresh successful execution in this review.
Inspect the walkthroughBehavior · proof and limits · source checks＋
Follow the source behavior
A synthetic rest.approval.protected command has write and external-side-effect declarations. The fixture sends a request first without approval evidence, then with a receipt bound to the operation and input.
Declare the boundary
The fixture defines a command with execution.effects set to write and external-side-effect, and execution.approval.required set to true.
Inspect the denied request
The first test binds a handler with a call counter. Without a receipt, it expects HTTP 403, APPROVAL_REQUIRED with reason missing_receipt, and calls equal to zero.
Inspect the approved request
The second test provides a receipt through createFetchHandler's approvalReceipt option and an approval port with a controlled clock. The response is expected to be 200 with value ran.
Apply the pattern to your side effect
Replace the synthetic handler with your operation and trusted receipt source. Add tests for the exact subject, operation, input, expiry, and effect requirements your application uses.
What this example establishes＋
Source demonstrates
The inspected denial test asserts that the handler is not invoked when a required receipt is missing.
The approved case adapts receipt evidence outside the operation input.
The fixture has an inspectable positive and negative request path.
Does not demonstrate
A fresh successful execution in this review.
An end-to-end human approval UI or trusted production receipt issuer.
A real external write: the approved handler only returns a fixture value.
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＋
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＋
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＋
Choose the code you are evaluating
There are two useful starting points: consuming published packages in your application, or studying a checked-out repository snapshot. Select one explicitly. Instructions for a monorepo can rely on workspace dependencies and repository scripts that a package consumer does not have.
