Build on Vadyl

Project capability surfaces

The central parity rule: projects can author, publish, install, govern, observe, and expose the same capability planes Vadyl uses internally.

This page is the documentation contract for the Project capability surfaces 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

Project capability surfaces owns the canonical product-facing contract described here; provider-specific machinery stays behind capability declarations.
The central parity rule: projects can author, publish, install, govern, observe, and expose the same capability planes Vadyl uses internally.
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 Project capability surfaces inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.
`ExposureBindingDescriptor`	Defines how Project capability surfaces appears through REST, OpenAPI, GraphQL, gRPC, SDK, CLI, MCP, dashboard, webhooks, realtime, and events.
`PlaneCapabilityGraph`	Places Project capability surfaces inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.
`EffectiveGovernanceEnvelope`	Canonical owner for Project capability surfaces; downstream surfaces derive from this rather than inventing their own truth.
`InstallationManifest`	Canonical owner for Project capability surfaces; downstream surfaces derive from this rather than inventing their own truth.
`ProjectCapabilityGrant`	Places Project capability surfaces inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.
`ProjectCapabilityConsumptionDescriptor`	Places Project capability surfaces inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.

Projection coverage

Surface kinds	`OperationProjectionSurface`, `CommandSurface`, `ToolSurface`, `UiProjectionSurface`, `GovernancePolicySurface`, `AgentSkillSurface`, `WorkflowSurface`, `AnalyticsSurface`, `EventVocabularySurface`
Projection facets	`ExposureBindings`, `PlaneCapabilityGraph`, `Operations`, `Cli`, `Observability`, `Agents`, `Workflows`, `Measures`
Protocols	`Rest`, `OpenApi`, `Sdk`, `Cli`, `Mcp`, `Dashboard`, `Webhook`, `Realtime`, `Event`
Public projections	REST; OpenAPI; SDK; CLI; MCP; dashboard actions; automation actions; webhooks; realtime; REST operations; OpenAPI operations; SDK namespaces; CLI command groups; MCP tools; workflow starts; agent skills; realtime channels

Project-scope parity

Provider projects publish safe slices of their own product model rather than asking consumers to call platform-private primitives.
Consumer projects install pinned versions with explicit grants, billing attribution, branch policy, environment policy, and revocable lifecycle state.
Every installed projection remains project-scoped: tenant, project, branch, publication, installation, actor, grant, quota, and descriptor hash travel together.

Publish, install, consume

ProjectCapabilitySurfaceManifest can select entities, operations, CLI commands, workflows, agent skills, analytics measures, events, webhooks, realtime channels, auth schemes, and runtime handlers.
ExposureBindingDescriptor maps each selected slice into protocols without changing semantics per protocol.
Published versions are immutable; upgrades, deprecations, revocations, and grant changes are explicit lifecycle events.

Consumption evidence

ProjectCapabilityConsumptionDescriptor records provider project, consumer project, installation id, protocol, exposed operation, actor, grant, quota dimension, billing scope, correlation id, and reason-code block.
Consumption evidence feeds billing, quota reservations, audit, dependency impact, PCG traversal, and explainability.
Revoked, suspended, expired, or capability-unsatisfied installs fail closed before the operation dispatcher runs.

Runtime behavior

project runtime compiler
branch-aware publication
surface manifest validator
install grant resolver
consumption evidence emitter
surface manifest compiler
publication registry
installation resolver
grant narrowing evaluator
exposure binding projector
PCG dependency indexer

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`
Observability	`/api/Observability`	8	`GET Entries` `GET Entries/{id}` `GET Trail/{entityName}` `GET Trails`
Explainability	`/api/Explainability`	15	`GET surface` `GET project-runtime` `GET publication/latest` `GET publication/{publicationVersion:long}`

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.
SDK	`agents`	definitions, runs, plans, memory, skills, model bindings, token accounting, MCP exposure. Rendered methods: 6.
SDK	`automation`	compile, definitions, runs, approvals, attempts, signals, compensation. Rendered methods: 6.
SDK	`events`	emit, list, get, tail, replay, consumer offsets, ordered stream helpers. Rendered methods: 2.
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.
CLI	`vadyl agent`	List, inspect, run agents. Rendered commands: 7.
CLI	`vadyl automation`	Compile definitions, manage runs, approvals, attempts, signals, compensation. Rendered commands: 10.
CLI	`vadyl events`	Tail / replay / search canonical event log. Rendered commands: 3.

Input request and output

project-capability-surfaces.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": "project-capability-surfaces",
  "publicationVersion": 412,
  "explain": true
}

Limits and quotas

Error model

Error	Meaning

Observability and explainability

Related references

Full surface atlas

Exposure bindings