The promise is narrower than the workflow name
A contract should name an observable result, not a broad aspiration. For invoice.create_draft, the promised result is a specific draft record whose saved values satisfy the contract. “Handle accounts payable” cannot determine whether a particular run succeeded.
Separate the output schema from the permitted system effect. Producing a valid bill object and creating that bill in an ERP are different results. A read-only extraction contract can succeed without a write; a draft-creation contract cannot.
| Contract element | Question it answers |
|---|---|
| Input schema | What records and documents are accepted? |
| Output schema | What structured result must be produced? |
| Required verifiers | What evidence establishes that the result passes? |
| Action boundary | Which system mutations are permitted? |
| Execution limits | Which data, spending, and time constraints apply? |
| Receipt requirements | Which references explain the result and effect? |
Make policy explicit
Required checks need explicit applicability rules. A purchase-order-backed invoice and a non-PO invoice are different cases; the runtime should not quietly skip a PO check because no order was supplied. Either the contract supports that branch or the input is outside its scope.
Matching tolerances are business policy, not model preference. Specify whether a tolerance applies per line or per invoice, before or after tax, and in which currency precision. A routing decision must not relax those rules to obtain a passing result.
Pin meaning as well as structure
A contract version pins the input and output schemas, verifier requirements, action semantics, and evidence expectations. Record the versions of referenced policies and verifiers so that a later change does not alter the interpretation of an old receipt.
A renamed optional field and a change from creating a draft to posting a bill are not equivalent updates. Plan a deliberate migration whenever completion, permissions, or required evidence changes. Test existing fixtures against the new version before switching a workflow.
Review a contract like a business operation
Exercise the runtime, integration, and verifiers together. Include source changes, missing context, duplicate submissions, and interrupted writes so the contract is evaluated against the full business operation.
- Ask what happens when a required source is unavailable, stale, or contradictory.
- Confirm that excluded actions cannot be enabled by instructions inside an input document.
- Require a recovery path for an unknown write outcome and a defined duplicate policy.
- Check that the receipt proves the claimed boundary, without implying approval or payment.
Missing a detail or found a problem?
Send a documentation question →