Build on Vadyl

Projects & hierarchy

Nested projects with inherited governance, providers, policies, federation. Closure-table topology, ~30-axis envelope.

This page is the documentation contract for the Projects & hierarchy surface in Vadyl's final form. It is not a marketing summary: it names the authorities, projections, runtime behavior, examples, limits, errors, and observability expectations that every product implementation must honor.

What this surface owns

Projects & hierarchy owns the canonical product-facing contract described here; provider-specific machinery stays behind capability declarations.
Nested projects with inherited governance, providers, policies, federation. Closure-table topology, ~30-axis envelope.
The final docs treat this as complete: REST, GraphQL, gRPC, SDK, CLI, MCP, dashboard, observability, limits, errors, and explainability are all covered as projections of one authority.

Canonical authorities

Authority	Role
`ProjectCapabilitySurfaceManifest`	Places Projects & hierarchy inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.
`ExposureBindingDescriptor`	Defines how Projects & hierarchy appears through REST, OpenAPI, GraphQL, gRPC, SDK, CLI, MCP, dashboard, webhooks, realtime, and events.
`PlaneCapabilityGraph`	Places Projects & hierarchy inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.
`EffectiveGovernanceEnvelope`	Canonical owner for Projects & hierarchy; downstream surfaces derive from this rather than inventing their own truth.

Projection coverage

Surface kinds	`OperationProjectionSurface`, `CommandSurface`, `ToolSurface`, `UiProjectionSurface`, `GovernancePolicySurface`
Projection facets	`ExposureBindings`, `PlaneCapabilityGraph`, `Operations`, `Cli`, `Observability`
Protocols	`Rest`, `OpenApi`, `Sdk`, `Cli`, `Mcp`, `Dashboard`
Public projections	REST; OpenAPI; SDK; CLI; MCP; dashboard actions; automation actions; webhooks; realtime

Project-scope parity

Publish, install, consume

Consumption evidence

Runtime behavior

project runtime compiler
branch-aware publication
surface manifest validator
install grant resolver
consumption evidence emitter

REST and controller surface

Code-backed controllers are listed here so the docs menu does not hide the real endpoint surface. The complete route-by-route table remains in the REST controller atlas.

Controller	Base route	Endpoint count	Examples
Projects	`/api/projects`	14	`POST create` `GET resolve` `POST {parentProjectId}/children` `GET {projectId}/provider-bindings`
Surface	`/api/Surface`	9	`GET /` `GET {id}` `GET {id}/is-installed` `POST /`
ContractProjection	`/api/ContractProjection`	4	`GET descriptor` `GET {language}/declarations` `GET cli` `GET events`
Operation	`/api/Operation`	2	`POST Execute` `POST Plan`
PlaneCapabilityGraph	`/api/PlaneCapabilityGraph`	2	`GET descriptor` `GET nodes/{kind}`
Usage	`/api/Usage`	7	`GET {projectId}/events` `GET {projectId}/rollups` `GET {projectId}/quotas` `POST {projectId}/quotas`

SDK and CLI surface

Projection	Namespace / group	Coverage
SDK	`surfaces`	publish, validate, describe, install, upgrade, grant, consume, invoke, explain, suspend, resume, revoke project capability surfaces. Rendered methods: 10.
SDK	`platform`	provider health/capabilities, runtime fabric scaling, distribution, version governance, data portability. Rendered methods: 12.
SDK	`branching`	branches, commits, workspaces, sandboxes, proposals, environments, deploy, rollback. Rendered methods: 5.
CLI	`vadyl surface`	Publish, validate, describe, install, upgrade, grant, consume, explain, suspend, resume, and revoke project capability surfaces. Rendered commands: 12.
CLI	`vadyl project`	Create, suspend, archive, traverse the project hierarchy. Rendered commands: 7.
CLI	`vadyl graph`	Inspect PCG descriptors, nodes, edges, actions, triggers, measures, effects, policies, and transforms. Rendered commands: 6.

Input request and output

projects-hierarchy.surface

POST /api/projects/create HTTP/1.1
Host: api.vadyl.app
Authorization: Bearer $VADYL_TOKEN
X-Vadyl-Tenant: acme
X-Vadyl-Project: billing
Content-Type: application/json

{
  "surface": "projects-hierarchy",
  "publicationVersion": 412,
  "explain": true
}

Limits and quotas

Error model

Error	Meaning

Observability and explainability

Related references

Full surface atlas

Exposure bindings