Policies

Declarative access control that AI agents can reason about before executing capabilities

What are Policies?

Policies are declarative access control rules that gate capability execution. Every capability lists one or more policies that govern who can invoke it. Before a capability runs, the policy engine evaluates all governing policies against the current actor's context. If no policy grants access, the capability is denied.

Because policies are declared in YAML (not buried in middleware or decorators), AI agents can read, reason about, and propose changes to access control with the same confidence they have for any other spec.

PolicySpec Structure

interface PolicySpec {
  name: string;               // unique policy name
  description: string;        // what this policy controls
  actor: string;              // actor type (e.g. "admin", "member", "workspace_owner")
  capabilities: string[];     // capabilities this policy governs
  conditions: PolicyCondition[]; // conditions that must be met
  effect: 'allow' | 'deny';  // whether the policy grants or denies access
}

Policy Effect

Each policy has an effect that determines what happens when its conditions are met:

• allow — The actor is granted access to the listed capabilities when conditions are satisfied
• deny — The actor is explicitly denied access to the listed capabilities when conditions are satisfied. Deny policies take precedence over allow policies.

Condition Operators

Conditions specify what must be true about the actor or context for the policy to apply. Each condition has a field, an operator, and a value.

How Policies Bind to Capabilities

The binding is bidirectional in spec and unidirectional in the graph. In the YAML specs, a policy lists the capabilities it governs, and a capability lists the policies that gate it. In the AI System Graph, this creates governed_by edges from each capability to each of its governing policies.

When the policy engine evaluates a capability invocation, it collects all policies whose capabilities array includes the invoked capability. It then evaluates each policy's conditions against the actor context. The result is determined by the effect of matching policies, with deny taking precedence.

YAML Example: SaaS Billing Policies

Here are admin and workspace owner policies from the SaaS billing example:

policies:
  - name: admin_full_access
    description: System administrators have unrestricted access to all capabilities
    actor: admin
    effect: allow
    conditions:
      - field: caller.role
        operator: eq
        value: admin
    capabilities:
      - create_user
      - get_user
      - create_workspace
      - get_workspace
      - transfer_workspace_owner
      - list_workspace_members
      - add_workspace_member
      - create_subscription
      - cancel_subscription
      - upgrade_subscription
      - downgrade_subscription
      - generate_invoice
      - void_invoice
      - get_invoice

  - name: workspace_owner_manage
    description: Workspace owners can manage their own workspaces and related billing
    actor: workspace_owner
    effect: allow
    conditions:
      - field: caller.id
        operator: is_owner
        value: resource.workspace.owner_id
    capabilities:
      - transfer_workspace_owner
      - add_workspace_member
      - create_subscription
      - cancel_subscription
      - upgrade_subscription
      - downgrade_subscription
      - get_invoice

  - name: member_read_only
    description: Regular members can only read data within their workspace
    actor: member
    effect: allow
    conditions:
      - field: caller.role
        operator: in
        value:
          - member
          - billing_admin
      - field: action
        operator: in
        value:
          - get_user
          - get_workspace
          - get_invoice
          - list_workspace_members
    capabilities:
      - get_user
      - get_workspace
      - get_invoice
      - list_workspace_members

Priority Ordering

When multiple policies match a capability invocation, the framework evaluates them in the order they appear in the spec. However, the fundamental rule is that deny effects always override allow effects. If any matching policy denies access, the capability is denied regardless of other allow policies.

Within the same effect type, more specific policies (those with more conditions or narrower actor types) should be listed before broader policies. This gives you fine-grained control over access decisions.

Graph Relationships

Each policy creates edges in the AI System Graph:

• capability:create_subscription --governed_by--> policy:admin_full_access
• capability:create_subscription --governed_by--> policy:workspace_owner_manage
• capability:create_subscription --governed_by--> policy:billing_admin_manage_subscriptions

This lets an AI agent quickly answer "who can create a subscription?" by traversing the governed_by edges from capability:create_subscription and inspecting each policy's conditions and effect.

AI-Safe Change Workflows

Policies are flagged in change plans whenever a capability change could affect access control. If a new capability is added, the Change Protocol checks whether adequate policies exist for it. If a policy is modified, the impact analysis identifies all capabilities governed by that policy. When policies are affected by a change, the plan generator adds human review flags, because access control changes always warrant human verification.