Contracts and rules
Look up the contract format, rule checks, judge checks, and the rule language.
Look up the contract format, rule checks, judge checks, and the rule language.
A contract governs one action. Its checks say what must hold for the action to run as proposed, and each names the verdict to apply when it doesn't. For a how-to, see Write contracts.
Contract files
Contracts live in the project's contracts/ folder, as .yaml, .yml, or .json. A file holds one contract at its top level, several documents, or a contracts: list. bindings.yaml and files starting with an underscore aren't contracts.
Keep in mind: Two contracts with the same id and version are refused, because a receipt names the rule and version that decided it.
| Field | Required | Description |
|---|---|---|
id | Yes | family.snake_case, such as payment.daily_limit. |
version | No, 1 | A whole number from 1. |
status | No, draft | See Status. |
action | Yes | The action governed. "*" means every action, narrowed by applies_when. |
applies_when | No | A rule. The contract applies only when it holds. A selector that can't be evaluated keeps the contract in, and its error denies. |
governs | No | The plain rule, for people. |
source | No | Where it came from: document, page, section, block ids, and text. |
checks | Yes | One or more, each with a unique id. |
review | No | The compiler's open issues: code, explanation, and resolved with a note once settled. |
Status
| Status | Evaluated | Enforced |
|---|---|---|
draft | No. | No. |
testing | Yes, in shadow, and recorded. | No. |
live | Yes. | Yes. |
retired | No. | No. |
Rule checks
A rule check decides a fact.
| Field | Required | Description |
|---|---|---|
id | Yes | Unique within the contract. |
check | Yes | A rule that must hold. |
stage | No, constraint | pre guards the rest: a failed pre at DENY skips the constraints. |
on_fail | No, DENY | OBSERVE, ESCALATE, or DENY. BLOCK is accepted as DENY. |
reason | No, <id> failed | Shown to the model and on the receipt. |
obligations | No | A mapping carried into the escalation, such as approver_role. |
Judge checks
A judge check asks coco-classifier a yes or no question. Yes means the check fails.
| Field | Required | Description |
|---|---|---|
id | Yes | Unique within the contract. |
judge.question | Yes | Phrased so yes means the check fails. |
judge.reads | No, [args, conversation] | From args, state, session, conversation, agent, and clause. clause is the contract's source text. |
judge.criteria | No | More guidance for the classifier. |
escalate_at | No | The probability at which the check escalates, above 0 and at most 1. 0.5 when neither threshold is set. |
deny_at | No | The probability at which the check denies. Not below escalate_at. |
on_error | No, ESCALATE | The verdict when the classifier fails, answers late, or isn't configured. |
reason | No | Shown to the model and on the receipt. |
A check has check: or judge:, never both. A judge check runs only when no rule denied, and can only raise a verdict.
The rule language
Rules use Python expression syntax over six names:
| Name | Contents |
|---|---|
action | The action. |
args | The arguments the model proposed. |
state | Facts your application supplied. |
session | What already ran in this session. |
limits | The project's numbers. |
agent | The agent's identity. |
- Allowed: Comparisons (
==,!=,<,<=,>,>=,in,not in,is,is not),and,or,not, arithmetic (+,-,*,/,%), lists, field and subscript reads, and the literalstrue,false, andnull. - Not allowed: Any other call, lambdas, comprehensions, and names or attributes starting with an underscore.
Functions are called by name with positional arguments:
| Function | Result |
|---|---|
matches(text, regex) | True when the regex is found in the text. A missing value never matches. |
all_in(items, allowed) | True when every item is allowed, with text compared case-insensitively. No items is true. |
len, lower, upper, strip, abs | As in Python. A missing value reads as null. |
min, max | Of the arguments, or of one list. |
Examples:
args.amount <= limits.auto_release_limit
state.account.status == "active"
"payee_manager" in state.initiator.roles
session.total.amount + args.amount <= limits.daily_cap
matches(args.memo, "\\bAPC-[0-9]{4}-[0-9]{4}\\b")
lower(args.recipient) in state.allowed_recipients
all_in(args.recipients, state.contacts)Missing fields
A missing field reads as null, so an equality check against it fails. An ordering comparison against null is an error, and an error is DENY. A missing number never passes a limit.
Session fields
session counts the calls that ran in this session. A stopped call isn't counted.
| Field | Contents |
|---|---|
session.calls | Calls that ran. |
session.actions[name] | Calls of one action that ran. |
session.last_action | The last action that ran. |
session.total.<field> | The running sum of a numeric argument over the calls to this action that ran. Zero on a first call. |
Which verdict wins
The most severe verdict among live contracts wins: DENY, then ESCALATE, then OBSERVE, then AUTO_EXECUTE. With no finding, the verdict is AUTO_EXECUTE and the reason is Every check passed.