Policy file
The schema of verdock.yaml, the YAML subset it accepts, how amounts are written and how the policy hash is computed.
On this page
A policy says, for each named operation, how far an agent can go on its own. The model proposes an operation and an amount. decide() answers from the policy alone. Nothing reads free text.
Schema#
version: 1
operations:
payout:
level: Execute within Limits
max_amount_minor: 5000
approval_above_minor: 2000
currency: USD
retry: never
credit_limit:
level: Execute with Approval
approval_bands:
large:
above_minor: 200000
approvers_required: 2
caps:
per_customer_per_day_minor: 10000
team_per_day_minor: 50000
egress:
allow_hosts:
- api.example.com| Key | Rule |
|---|---|
version | Must be 1. |
operations.NAME.level | Required. One of Assist, Draft, Execute with Approval, Execute within Limits. |
max_amount_minor | Optional integer, zero or more. |
approval_above_minor | Optional integer, zero or more. |
currency | Optional. Three upper case letters. |
retry | never (default) or safe. |
approvers_required | Optional positive integer. |
approval_bands | Optional mapping of named bands, each with above_minor and approvers_required. Thresholds are exclusive and must differ. |
caps.per_customer_per_day_minor, caps.team_per_day_minor | Optional integers. The guard and adapters need both. |
egress.allow_hosts | Optional list of lower case host names. Without it nothing can leave. |
Amounts are integers in minor units. Unknown keys are rejected.
The YAML subset#
Policy files are JSON (.json) or a YAML subset (any other suffix).
- Block mappings
key: value, with keys of letters, digits,_,.and-. - Nested mappings by indentation with spaces. Tabs are rejected.
- Block lists of scalars.
- Scalars: integers without leading zeros,
true,false, double quoted strings, single quoted strings and plain strings. #comments at the start of a line or after a space.
Anything else is rejected with a PolicyError that names the line: flow collections, anchors, tags, block scalars, multiple documents, floats, null, and ambiguous words such as yes, no, on, off.
The policy hash#
policy_hash() is the SHA256 hex digest of the validated policy encoded as JSON with sorted keys, no whitespace, UTF-8. Validation fills retry with its default before hashing, so a file that omits retry hashes the same as one that writes retry: never. Any change to a level, limit, currency, retry rule or cap changes the hash. Approvals and receipts bind to it.