Cascade

Cascade

The Cascade is how Policy scales across an org with multiple teams.

Three tiers — org floor, project floor, agent override — merged with strictest-wins semantics. Each level can tighten the floor below it; none can relax it.

Per governed-agents.md §6. The Cascade is what makes Policy authoring tractable when one company has 10 teams shipping 50 agents.

At a glance

Three tiers	Org floor → Project floor → Agent override
Merge semantics	Strictest-wins (enabled: true always wins; block > notify > log; numeric ceilings — lower wins; contains — union / logical AND)
Authored at	Each tier by a different role (Org admin / Project admin / Agent owner)
Output	The merged effective Policy; the input to the Policy compiler
Applies before	The Compiled Policy is emitted (cascade merge happens server-side, in-memory)

The three tiers

ORG FLOOR (the bottom; applies to every project and agent)
   │  authored by org admins; cannot be relaxed below
   │  typical content: compliance pack(s), forbid PII exfiltration, audit signing,
   │                   `forbidden_capabilities` floor (operator can never lift)
   ▼
PROJECT FLOOR (per-project additions)
   │  authored by project admins; cannot be relaxed below the org floor
   │  typical content: project schemas, integrations, tool sets,
   │                   project-specific compliance packs
   ▼
AGENT OVERRIDE (per-agent specifics)
      authored by agent owners; cannot relax org or project floors
      typical content: typical-session shape, per-tool constraints,
                       narrow exceptions, sandbox-spec parameters

Strictest-wins merge — examples

Aspect	Org floor	Project floor	Agent override	Effective
tools.deny: ["Bash(curl:*)"]	yes	(silent)	(tries to remove)	denied — agent can't lift the floor
network.allow_domains	[api.anthropic.com]	adds [github.com]	adds [localhost:5432]	union of all three (additive)
budget.tokens_per_day	1,000,000	500,000	100,000	100,000 (lower wins)
compliance_tags	[SOC2:CC6.1]	adds [ISO42001:6.2.3]	adds [HIPAA:164.312]	union of all three
tools.deny_if_tainted: { phi → [WebFetch] }	(silent)	yes	(tries to remove)	denied — taint floor stands

Forbidden capabilities — the absolute floor

When a function declares forbidden_capabilities: [code_execution, sor_arbitrary_write] at any tier, no override at any tier can lift them. Lifting requires editing the function definition itself — a separately-audited Compliance action.

This is what makes the cascade safe: the floors are not just defaults, they are enforced minimums that downstream tiers cannot lower.

Roles per tier

Role	Org level	Project level	Agent level
Org admin	Author org floor; manage providers; manage MCP registry	Inherits project rights	Inherits agent rights
Project admin	—	Author project floor; manage agents	Inherits agent rights
Agent owner	—	—	Author agent overrides; provision sandboxes; view this agent's audit
Auditor	View org-wide audit	View project audit	View agent audit (read-only)

A Team is the access-control unit (SSO-group-backed). Roles are assigned per team, per cascade level.

Authoring conveniences feed each tier

Each tier can be authored using:

• Functions + Categories + Concerns + Capabilities (the intent-to-policy authoring conveniences)
• Compliance Packs (Compliance Pack card) — pre-built bundles per regulation (EU AI Act, OWASP LLM, GDPR, …)
• Manual Rego overlay — operator-specific tweaks

The authoring resolver collapses these into a normalized Policy at each tier. Then the Cascade merger combines tiers strictest-wins.

How the Cascade interacts with the Compiled Policy

The Cascade is a Policy-time concept. By the time the Compiled Policy is emitted, the cascade merge is already complete — the Compiled Policy reflects the merged effective Policy. Providers don't see the tier structure; they see the final result.

┌──────────────────────────┐
│ Org floor Policy (Rego)  │──┐
└──────────────────────────┘  │
┌──────────────────────────┐  ├─▶ Cascade merger
│ Project floor (Rego)     │──┤      (strictest-wins)
└──────────────────────────┘  │             │
┌──────────────────────────┐  │             ▼
│ Agent override (Rego)    │──┘     merged effective Policy
└──────────────────────────┘                │
                                            ▼
                                    Policy compiler
                                            │
                                            ▼
                              Compiled Policy (by aspect)
                                            │
                                            ▼
                                    Providers per ring

Because-trail (provenance)

Every effective rule carries a chain back to the operator action that produced it — including which tier contributed:

detect_pii (block)
  ⤷ Concern: data_leak
      ⤷ Category: customer_pii    ✓ ticked at onboarding (project tier)
      ⤷ Compliance pack: eu-ai-act ✓ applied at org floor
  ⤷ Org floor:                    ✓ inherited from "acme-baseline"
Function: refund_processor
Set up by: jens@acme.com on 2026-04-25 14:32 UTC

The because-trail is rendered in the dashboard whenever an operator inspects a rule and is preserved in the Compiled Policy's metadata for forensic replay.

Engines that operate on the Cascade

Engine	What it does	Status
Cascade merger	Strictest-wins merge across tiers; produces effective Policy	concept (within Policy compiler)
Authoring resolver	Per-tier: collapse function/categories/concerns/packs into Rego	shipped (~40 LOC, live on main)
Tier RBAC	Enforces who can author at each tier	concept (within operator-cli + dashboard)
Because-trail recorder	Preserves which tier introduced each rule	concept

Edge cases

• Agent runs while org floor changes — the Compiled Policy is re-compiled and re-pushed; in-flight calls complete against the previous version, the next call uses the new version.
• Project policy contradicts org floor — rejected at apply time. The operator sees the contradiction in the dashboard; the merge does not silently relax the floor.
• Agent override tries to lift a forbidden capability — silently denied. The dashboard surfaces the attempt for the agent owner.

Related concepts

• input to → Policy compiler — emits Compiled Policy after merge
• scoped by → Project and Team — who authors at which tier
• persisted in → Compiled Policy — final merged result with because-trail metadata
• applied by → Sync — pushes new Compiled Policy when any tier changes

Authoritative docs

Topic	File
Vision	governed-agents.md §6 — three-tier cascade
Authoring conveniences	intent-to-policy.md — function/category/concern/capability
Component	cascade-merge-engine

Common confusions

• Cascade ≠ Pipeline. The Cascade is Policy authoring; the Pipeline is runtime enforcement. The Cascade merges tiers into one effective Policy; the Pipeline runs the resulting Compiled Policy on every governed call.
• Strictest-wins is not "last-write-wins". Lower-tier rules can only tighten, never relax. There's no order-dependence; you can author tiers in any order.
• The cascade is a Policy-time concept. By the time the Compiled Policy is emitted, the cascade merge is finished. Providers consume the final result.
• Forbidden capabilities are not overridable. They're not strictest-wins defaults; they're hard floors. Editing them requires Compliance action, audited separately.