Governance envelopes

A governance envelope is the typed envelope of what a project (and its descendants) is allowed to do. Allowed providers, allowed regions, allowed federation targets, allowed connectors, quotas, minimum auth strengths, allowed connection types, and ~30 other axes. Vadyl compiles a project's effective envelope from its full ancestry chain — closer ancestors don't override farther ones; they tighten them.

Why envelopes

Vadyl supports nested projects: an organization can have child projects, those can have grandchild projects, and so on. Without a governance model, a child could drift outside what the parent allowed — bind to a forbidden region, federate with an unapproved peer, exceed parent quotas. Envelopes prevent that, structurally.

Merge discipline

Envelopes merge from root to descendant with typed reduction rules — never ad hoc:

• Allowlists narrow (intersection): AllowedProviderTypes, AllowedRegions, AllowedFederationTargets.
• Denylists grow (union): DeniedConnectionTypes, DeniedEgressHosts.
• Quotas shrink (min): MaxStorageBytes, MaxMonthlyEvents, MaxConcurrentRuns.
• Auth strength rises (max): MinimumAuthStrength only ever increases as you walk down the tree.
• Permissions AND: a child can only have a permission if every ancestor grants it.
• Restrictions OR: a child has a restriction if any ancestor enforces it.

These rules guarantee that a descendant's effective envelope is always a subset of (or equal to) every ancestor's. Tightening at the root automatically cascades down on the next compile.

Where envelopes are enforced

Enforcement is fail-closed at every mutation site:

• Child project provisioning
• Provider binding creation / update
• Cache binding creation / update
• Governed connection creation / update
• Capability grant issuance
• Quota mutation
• Federation contract creation
• Installable surface publishing / installation
• Branching mutations (branches, commits, sandboxes, deployments)
• Identity / database connector binding

If the envelope cannot be resolved (control-plane corrupted, ancestry chain broken), the descendant is marked Corrupt with a zero-default integrity status — it cannot serve traffic and cannot be mutated until the chain is repaired.

Tightening cascades

When a parent envelope tightens — e.g. removing a provider fromAllowedProviderTypes — every descendant's next compile observes the new envelope. Bindings that previously resolved but no longer satisfy the envelope are dropped, and the affected runtime descriptor is marked corrupt with a truthful reason code (governance-envelope-tightened). Operators see the change in the dashboard and the explainer.

Capability grants

Inside the envelope, projects receive explicit, time-bounded capability grants. A grant is a typed authorization — "this project may host child projects", "this project may federate cross-project entities", "this project may publish installable surfaces". Grants are issued by an authority (typically the parent), are auditable, and expire if not renewed.

Why this matters

Multi-tenant SaaS, agency-style organizations, regulated industries, and AI agents that provision their own sub-environments all need a guarantee that descendants stay inside parent-imposed boundaries. Envelopes give that guarantee structurally — not as a runtime check you have to remember to add, but as a compile-time invariant baked into every mutation site.