# Model inputs, outcomes and failures

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

Source context: Source-guided
Source: https://github.com/lssm-tech/contractspec/blob/d58fa5b7de53a947811e5cc68346be028ce18528/packages/foundation/contracts-spec/src/operations/operation.ts

## 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 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.

## Related examples

- [Capture now, complete when ready](https://lssm.co/examples/form-showcase/): Use form contracts to accept a minimal intake while keeping missing readiness fields visible.