Coco
Look something up

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.

FieldRequiredDescription
idYesfamily.snake_case, such as payment.daily_limit.
versionNo, 1A whole number from 1.
statusNo, draftSee Status.
actionYesThe action governed. "*" means every action, narrowed by applies_when.
applies_whenNoA rule. The contract applies only when it holds. A selector that can't be evaluated keeps the contract in, and its error denies.
governsNoThe plain rule, for people.
sourceNoWhere it came from: document, page, section, block ids, and text.
checksYesOne or more, each with a unique id.
reviewNoThe compiler's open issues: code, explanation, and resolved with a note once settled.

Status

StatusEvaluatedEnforced
draftNo.No.
testingYes, in shadow, and recorded.No.
liveYes.Yes.
retiredNo.No.

Rule checks

A rule check decides a fact.

FieldRequiredDescription
idYesUnique within the contract.
checkYesA rule that must hold.
stageNo, constraintpre guards the rest: a failed pre at DENY skips the constraints.
on_failNo, DENYOBSERVE, ESCALATE, or DENY. BLOCK is accepted as DENY.
reasonNo, <id> failedShown to the model and on the receipt.
obligationsNoA 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.

FieldRequiredDescription
idYesUnique within the contract.
judge.questionYesPhrased so yes means the check fails.
judge.readsNo, [args, conversation]From args, state, session, conversation, agent, and clause. clause is the contract's source text.
judge.criteriaNoMore guidance for the classifier.
escalate_atNoThe probability at which the check escalates, above 0 and at most 1. 0.5 when neither threshold is set.
deny_atNoThe probability at which the check denies. Not below escalate_at.
on_errorNo, ESCALATEThe verdict when the classifier fails, answers late, or isn't configured.
reasonNoShown 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:

NameContents
actionThe action.
argsThe arguments the model proposed.
stateFacts your application supplied.
sessionWhat already ran in this session.
limitsThe project's numbers.
agentThe agent's identity.
  • Allowed: Comparisons (==, !=, <, <=, >, >=, in, not in, is, is not), and, or, not, arithmetic (+, -, *, /, %), lists, field and subscript reads, and the literals true, false, and null.
  • Not allowed: Any other call, lambdas, comprehensions, and names or attributes starting with an underscore.

Functions are called by name with positional arguments:

FunctionResult
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, absAs in Python. A missing value reads as null.
min, maxOf 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.

FieldContents
session.callsCalls that ran.
session.actions[name]Calls of one action that ran.
session.last_actionThe 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.


On this page