Write contracts
Write rules and judge checks by hand, and test a contract before it goes live.
Write rules and judge checks by hand, and test them before they go live.
Most contracts come from your policy documents. Write one by hand for what a policy doesn't state, such as a blocklist.
Create a contract
Save this as a YAML file in contracts/:
contracts:
- id: payments.send_limit # family.snake_case
version: 1
status: draft # draft | testing | live | retired
action: payments.send
governs: A payment above the limit waits for a person.
source: {document: Payments Policy, section: "2.1", text: "Payments above AUD 10,000 ..."}
checks:
- id: under_limit
check: 'args.amount <= limits.auto_release_limit'
on_fail: ESCALATE # OBSERVE | ESCALATE | DENY
reason: Above the auto-release limitA check is a condition that must hold, and on_fail is the verdict when it doesn't.
Rules read limits from coco.yaml:
limits:
auto_release_limit: 10000To see the contract, run coco contracts list. A malformed contract stops loading with an error naming the contract and the check.
Write the rule
A rule can read the call, your facts, the session, and the project's limits:
args.amount <= limits.auto_release_limit # the call, against the project's numbers
"payee_manager" in state.initiator.roles # facts from your systems
session.total.amount + args.amount <= limits.daily_cap # what already ran in this conversation
matches(args.memo, "\\bAPC-[0-9]{4}-[0-9]{4}\\b") # a pattern
lower(args.payee) not in ["apex corp", "shadow ltd"] # a blockliststate comes from your state provider, never from the model. For the full language, see Contracts and rules.
Keep in mind: A field the call lacks reads as null, and comparing a number against null denies. A missing number never passes a limit.
Choose a verdict
| Verdict | Use it when |
|---|---|
OBSERVE | The call may run, and the receipt should flag it. |
ESCALATE | A person decides. obligations tell the approver what's required. |
DENY | The call must never run as proposed. The reason goes to the model. |
The most severe verdict among live contracts wins.
Guard the rest with a pre check
A pre check runs first. When one fails at DENY, Coco skips the constraints behind it:
checks:
- id: account_active
stage: pre
check: 'state.account.status == "active"'
on_fail: DENY
reason: The source account is not activeNarrow when a contract applies
applies_when is a rule, and the contract applies only when it holds:
action: payments.send
applies_when: 'args.currency == "AUD"'action: "*" governs every action, usually narrowed with applies_when.
Add a judge check
A judge check asks the classifier about what no rule can see. Phrase the question so yes means the check fails:
checks:
- id: requested_by_user
judge:
question: Is this transfer something the user did not clearly ask for?
reads: [args, conversation, clause] # clause: the contract's source text
escalate_at: 0.5
deny_at: 0.9
reason: The transfer does not match what the user asked forSet classifier.url in coco.yaml or COCO_CLASSIFIER_URL. Without a classifier, every judge check takes its on_error verdict, ESCALATE by default.
Keep in mind: The hosted gate has no classifier today, so this applies on every connected project. Use judge checks for intent and prose, never for a hard limit. Results shows why.
Test it and make it live
Move the contract to testing, read what it would have done, then make it live:
coco contracts activate payments.send_limit --testing # recorded, never enforced
coco ledger # read what it would have done
coco contracts activate payments.send_limit --live # enforcedGood to know: coco contracts activate changes files that hold a contracts: list, as above. A file with one contract at its top level also loads, but activate skips it, so edit its status: by hand.
To try a call without a model, run:
python - <<'EOF'
from coco_sdk.project import load
engine = load().engine(mode="enforce")
d = engine.check("payments.send", {"amount": 25000, "payee": "Sunrise Capital"})
print(d.verdict, d.reason)
EOFOn a connected project, a contract you write by hand reaches the gate through an administrator. See Contracts on a connected project.