# Find the boundary that failed

Diagnose package, schema, execution and transport failures without changing several layers at once.

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

## Capture a small reproducible case

Record the package versions or commit, operation key and version, chosen adapter and sanitized request. Keep the first relevant error and trace identifier. Start from the boundary where the failure appears instead of reinstalling or regenerating the entire project.

Remove provider credentials and personal data from a reproduction. A fixture subject and a disposable handler are usually enough to isolate schema, registry or approval behavior.

## Use the symptom to choose the next check

A request can fail before the handler, inside business logic or after the handler returns. Distinguishing those points prevents changes that make the interface appear fixed while hiding the real issue.

| Symptom | Check first | Avoid assuming |
| --- | --- | --- |
| Package cannot be resolved | Selected registry, exact package version and public exports | A workspace path is a published import |
| Spec or handler missing | Registration, key/version and binding | A declaration executes merely because it exists |
| VALIDATION_FAILED | Declared input and adapter input mapping | A policy rejection caused the failure |
| UNAUTHENTICATED | Trusted adapter context | A role field in input authenticates the caller |
| APPROVAL_REQUIRED | Requirement, receipt and approval port | Any token-shaped value authorizes a request |
| Invalid output | Handler return value and output model | The failed response rolled back earlier effects |
| API works, MCP fails | Tool schema, identity and result handling | Both transports have identical wire semantics |

## Isolate one layer at a time

First confirm the operation is registered and bound. Then test the registry with the same valid input and a deliberately constructed fixture context. Finally invoke the actual adapter. This tells you whether the problem is in the handler or in transport/context mapping.

For approval failures, inspect the reason. Missing evidence and a missing approval runtime require different fixes. Keep the fail-closed behavior while correcting the host configuration.

## Check documentation provenance

If a copied snippet refers to a different metadata shape, import path or command flag, compare it with the selected version's source. The source-guided pages here deliberately identify their snapshot so differences can be examined.

When reporting a docs defect, include the page URL, package version, smallest failing snippet and expected result. That is more actionable than a screenshot of a large terminal log.