VERDOCK

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#

YAML
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
KeyRule
versionMust be 1.
operations.NAME.levelRequired. One of Assist, Draft, Execute with Approval, Execute within Limits.
max_amount_minorOptional integer, zero or more.
approval_above_minorOptional integer, zero or more.
currencyOptional. Three upper case letters.
retrynever (default) or safe.
approvers_requiredOptional positive integer.
approval_bandsOptional 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_minorOptional integers. The guard and adapters need both.
egress.allow_hostsOptional 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.