Skip to content
ContractSpec
Start here

Core guide · Concepts · 3 min read

Model inputs, outcomes and failures

Make the data boundary explicit while keeping business meaning in the operation and handler.

Source context

Source-guided · d58fa5b7

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 SEQUENCE

Understand how the ideas connect

01 / READING POINT

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.

1 / 4

0 points in your packet

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.

Give expected failures names

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 outcomeCaller concernWhere to investigate
Invalid requestCorrect the submitted dataInput schema and mapping
Expected business failureChoose another valid product actionDeclared result and handler
Denied executionSatisfy an authorized policy or approval pathHost decision context
Invalid handler outputReport or repair an implementation defectHandler 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.

Choose the check that answers the question.

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.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.