Reference

Exposure bindings

The canonical binding contract behind REST, OpenAPI, GraphQL, gRPC, SDKs, CLI, MCP, dashboard actions, webhooks, realtime channels, events, analytics, auth, runtime fabric scaling, and host imports.

An exposure binding is the complete statement that one canonical capability is visible through one protocol shape. It names the protocol, route/name, input and output contracts, error contract, authentication contract, authorization policy, grant set, rate limit, idempotency policy, observability policy, explainability reason block, stability state, and deterministic descriptor hash.

Binding descriptor

exposure-binding.example

{
  "bindingId": "rest:Entity.Order.Read",
  "tenantId": "acme",
  "projectId": "billing",
  "publicationVersion": 412,
  "surfaceKind": "OperationProjectionSurface",
  "surfaceName": "Order",
  "surfaceVersion": "412",
  "capabilityId": "Entity.Order.Read",
  "capabilityNodeId": "pcg:entity:Order:read",
  "protocolKind": "Rest",
  "exposureShape": "RestRoute",
  "routeOrName": "GET /api/Entity/Order/{id}",
  "inputContractRef": "contracts/Order.Read.Request",
  "outputContractRef": "contracts/Order.Read.Response",
  "errorContractRef": "contracts/ApiError",
  "authnContractRef": "auth/BearerProjectToken",
  "authzPolicyRef": "policy/Order.read",
  "requiredGrantSet": ["entity:Order:read"],
  "rateLimitPolicyRef": "quota/read/default",
  "idempotencyPolicyRef": null,
  "observabilityPolicyRef": "observability/entity-read",
  "explanationReasonCodeBlock": "reason/Order.read",
  "stability": "Stable",
  "deprecationPolicy": null,
  "descriptorHash": "sha256:6f6f..."
}

Protocol kinds

Protocol	Description
`Rest`	REST over HTTP route exposure.
`OpenApi`	OpenAPI operation emission derived from REST bindings.
`GraphQL`	GraphQL fields, mutations, and subscriptions.
`Grpc`	Generated proto contracts and gRPC method dispatch.
`Sdk`	Typed SDK method exposure.
`Cli`	Descriptor-driven CLI command exposure.
`Mcp`	MCP tools, resources, and prompts.
`Dashboard`	Official dashboard actions projected from canonical bindings.
`Webhook`	Outbound webhook topic delivery.
`Realtime`	WebSocket, SSE, and push subscription channels.
`Event`	Canonical event producers and consumers.

Exposure shapes

Shape	Description
`RestRoute`	HTTP method plus route template.
`OpenApiOperation`	OpenAPI operation entry.
`GraphQLField`	GraphQL Query field.
`GraphQLMutation`	GraphQL Mutation field.
`GraphQLSubscription`	GraphQL Subscription field.
`GrpcMethod`	gRPC method on a generated service.
`SdkMethod`	Typed SDK method.
`CliCommand`	CLI command with arguments/options.
`McpTool`	MCP callable tool.
`McpResource`	MCP readable resource.
`McpPrompt`	MCP prompt template.
`DashboardAction`	Dashboard button, menu entry, or route action.
`WebhookTopic`	Outbound webhook topic.
`RealtimeChannel`	Realtime subscription channel.
`EventProducer`	Surface emits a canonical event.
`EventConsumer`	Surface consumes a canonical event.
`AnalyticsQuery`	Analytics query exposed for evaluation.
`AnalyticsReport`	Analytics report projection.
`AnalyticsDashboard`	Analytics dashboard projection.
`AuthSchemeExposure`	Identity/auth exposure such as login, refresh, federation, challenge.

Stability states

State	Description
`Experimental`	Explicit opt-in required; no compatibility guarantees.
`Beta`	Broad availability; breaking changes possible with notice.
`Stable`	First-class support with compatibility guarantees.
`Deprecated`	Callable but superseded; requires deprecation policy and replacement.
`Retired`	Descriptor remains for traceability; runtime dispatch fails closed.

API operation kinds

Operation kind is the canonical verb used by route materialization, OpenAPI operation IDs, CLI command derivation, SDK methods, MCP tool names, and dashboard actions.

Operation kind	Description
`Create`	Create one resource.
`Read`	Read one resource by id.
`Update`	Update one resource.
`Delete`	Delete one resource.
`Upsert`	Create or update by identity.
`ReadByAlternateKey`	Read one resource by named alternate key.
`List`	List resources.
`Query`	Execute typed query/filter AST.
`Count`	Count matching resources.
`Exists`	Check existence.
`BatchCreate`	Create multiple resources.
`BatchUpdate`	Update multiple resources.
`BatchDelete`	Delete multiple resources.
`Upload`	Upload binary or source content.
`Download`	Download binary or source content.
`Stream`	Stream binary or event content.
`PresignDownloadUrl`	Create a signed download URL.
`PresignUploadUrl`	Create a signed upload URL.
`Copy`	Copy storage/source content.
`Move`	Move storage/source content.
`Trigger`	Trigger a task/workflow/action.
`Pause`	Pause a task, workflow, or surface.
`Resume`	Resume a paused task, workflow, or surface.
`Cancel`	Cancel a run or operation.
`Execute`	Execute a planned operation.
`Plan`	Plan an operation without applying.
`Preview`	Preview a change or migration.
`Diff`	Diff model, branch, environment, or schema state.
`Migrate`	Apply migration/evolution work.
`Snapshot`	Create or read a snapshot.
`Validate`	Validate descriptor, input, schema, or build.
`Subscribe`	Subscribe to realtime or event updates.
`Custom`	Connector or domain-specific operation.
`Invoke`	Invoke an authored handler through the execution coordinator.

API resource kinds

Resource kind	Description
`Entity`	Dynamic entity CRUD/query resources.
`Storage`	Blob/object/source asset storage resources.
`Scheduling`	Task definition, run, trigger, and attempt resources.
`Operation`	Canonical operation plan/execute resources.
`ControlPlane`	Tenant, organization, project, and platform control-plane resources.
`Schema`	Schema, migration, snapshot, transition, validation resources.
`Realtime`	Realtime subscription resources.
`Auth`	Authentication resources.
`Branching`	Branch, workspace, sandbox, proposal, environment resources.
`Connector`	Connector contracts, implementations, bindings, invocation resources.
`Identity`	Identity provider, subject, membership, policy resources.
`Email`	Email transport resources.
`Sms`	SMS transport resources.
`Webhook`	Webhook endpoint, receiver, delivery, receipt resources.
`AuthoredHandler`	Authored handler invocation resources.
`Analytics`	Analytics catalog, query, model, metric, report, dashboard, materialization resources.
`PlaneCapabilityGraph`	PCG descriptor and node resources.
`Automation`	Automation definition, run, approval, attempt, signal resources.
`Measure`	Measure descriptor and query resources.
`Agent`	Agent, run, plan, memory, model binding, skill, knowledge corpus, MCP resources.

Transport, body, and change tracking

Transports

Transport	Description
`Rest`	HTTP JSON/resource transport.
`WebSocket`	WebSocket realtime transport.
`Sse`	Server-sent event realtime transport.
`Internal`	Internal dispatcher/background transport.

Request body kinds

Body kind	Description
`None`	No request body.
`Json`	JSON request body.
`MultipartForm`	Multipart form upload body.
`OctetStream`	Binary octet-stream body.
`Stream`	Streaming body.

Change tracking

Tracking kind	Description
`None`	No change tracking or notification support.
`FieldNamesOnly`	Change events include field names only, never values.
`FullPayload`	Full-payload notification shape for explicitly safe internal or policy-granted surfaces.

Runtime fabric vocabulary

Runtime fabric is the placement and operator plane. It uses a separate topology vocabulary from the authored-code execution surfaces.

Project execution surfaces

Surface	Description
`Unspecified`	Fail-closed default. Never silently resolves or applies.
`ApiIngress`	Project HTTP API ingress surface; commonly load-balanced and scaled on request pressure.
`CoreHandler`	Authored core handlers in the project runtime topology; can scale independently from consumers and jobs.
`DurableWorkflow`	Authored durable workflows in the project runtime topology; pinned to publication and governed by workflow runtime policy.
`EventConsumer`	Authored event consumers; commonly autoscaled on queue depth, consumer lag, or custom PCG measures.
`ScheduledJob`	Authored scheduled jobs served by platform scheduling operators; often fixed or tightly capped.
`WebhookHandler`	Authored inbound webhook handlers; can be separately exposed, load balanced, and autoscaled.
`EdgeHandler`	Constrained authored edge handlers with edge-resource policy and distribution-origin integration.
`ManagementHandler`	Privileged authored management handlers; usually fixed, private, and heavily governed.
`RealtimeGateway`	Project realtime WebSocket/SSE subscription gateway; scales on connection and fanout pressure.

Runtime substrates

Substrate	Description
`Unspecified`	Fail-closed default. Permitted only before topology resolution.
`HostManaged`	In-process on the main Vadyl host.
`FixedInstance`	Pinned VM or dedicated instance.
`AutoscaledInstanceGroup`	Scaling group of substrate-managed VMs with declared autoscale metrics and instance ceilings.
`ServerlessContainer`	Scale-to-zero request-driven or queue-driven container with concurrency and resource-class policy.
`DedicatedContainer`	Long-lived dedicated container realization with manual or native autoscale policy.
`ClusteredRuntime`	Orchestrated cluster substrate. Kubernetes is one realization, not a canonical type.
`EdgeSubstrate`	Edge point-of-presence runtime substrate with edge CPU-time and memory budgets.

Scaling modes

Mode	Description
`Fixed`	Keep a fixed desired instance count; no manual mutation or autoscaler changes it.
`Manual`	Operators or automation set desired count inside canonical min/max and governance ceilings.
`Autoscale`	Desired count is driven by native or Vadyl-managed autoscale rules.

Scale partition modes

Partition	Description
`SharedPool`	All surfaces share one workload pool.
`PerSurface`	Each project execution surface realizes independently.
`NamedGroup`	Surfaces with the same scale group name share desired count and autoscale policy.

Autoscale strategies

Strategy	Description
`TargetTracking`	Keep a metric near a target value.
`StepScaling`	Apply explicit capacity changes when thresholds are crossed.
`Scheduled`	Apply planned min, max, or desired counts during time windows.
`Predictive`	Use a substrate or Vadyl model to forecast capacity before demand arrives.
`QueueDriven`	Scale from queue depth, consumer lag, or backlog age.

Autoscale metrics

Metric	Description
`SaturationPercent`	Running capacity divided by desired capacity.
`CpuUtilizationPercent`	CPU utilization from substrate telemetry.
`MemoryUtilizationPercent`	Memory utilization from substrate telemetry.
`RequestsPerSecondPerInstance`	Request rate normalized per running instance.
`InFlightRequestsPerInstance`	Concurrent request pressure per instance.
`LatencyP95Ms / LatencyP99Ms`	Tail latency measured at runtime or ingress.
`QueueDepth / ConsumerLagSeconds`	Backlog pressure for event and queue consumers.
`AcceleratorUtilizationPercent`	GPU, inference accelerator, or specialized device utilization.
`CustomPcgMeasure`	A PCG measure with compatible semantics, dimensions, freshness, grants, and a live sample source.

Resource classes

Resource class	Description
`Burstable`	Cost-efficient baseline with burst capacity.
`Standard`	General-purpose runtime class.
`ComputeOptimized`	CPU-heavy workloads.
`MemoryOptimized`	Memory-heavy workloads.
`AcceleratedTraining / AcceleratedInference`	GPU, neural accelerator, FPGA, or specialized inference class.
`EdgeIsolate`	Constrained edge runtime budget with CPU-time and isolate memory ceilings.
`ServerlessFunction`	Function-style runtime with request, concurrency, and wall-clock constraints.

Load-balancing modes

Load-balancing mode	Description
`None`	No managed load balancer requested.
`ManagedPublic`	Public load-balanced service endpoint.
`ManagedPrivate`	Private load-balanced service endpoint for internal traffic.
`MeshOnly`	Service-mesh or internal routing fabric only.

Platform operators

Operator	Description
`Unspecified`	Fail-closed default.
`EventOutboxProcessor`	Drains transactional outbox rows into the platform event log.
`EventRouter`	Routes canonical events to registered consumers with at-least-once delivery.
`WebhookDeliveryDispatcher`	Dispatches pending outbound webhook deliveries.
`InboundWebhookReconciler`	Reconciles inbound webhook receipts against the canonical event log.
`ScheduledJobScanner`	Scans triggers and materializes due scheduled runs.
`ScheduledJobDispatcher`	Claims and dispatches scheduled runs.
`ScheduledJobWorker`	Executes scheduled handler work.
`RealtimeSubscriptionFanout`	Fans out entity change events to realtime subscribers.
`CacheInvalidationPump`	Propagates cross-instance cache invalidations.
`ObservabilityDrainAudit`	Append-only audit-log drain.
`ObservabilityDrainDebug`	Best-effort debug trace drain.
`ObservabilityDrainOperational`	Backpressure-aware operational trail drain.
`BillingDrainMetering`	Usage metering drain.
`BillingDrainRollup`	Usage rollup aggregator.
`ProvisioningRecoverer`	Recovers stuck project provisioning runs.
`SchemaTransitionRecoverer`	Recovers stuck schema transition runs.
`EvolutionRecoverer`	Recovers stuck graph evolution runs.
`WorkflowRecoverer`	Recovers stale durable workflow instances.
`RuntimeFabricRecoverer`	Recovers stale runtime-fabric deployment intents.
`DatabaseSourceJobDispatcher`	Dispatches external-database-source jobs.
`StagingTtlSweeper`	Sweeps expired external database source staging rows.
`GracefulShutdownCoordinator`	Coordinates graceful shutdown across host background services.
`AuthoredWorkerPool`	Platform-owned pool that executes authored runtime code.

Capability host imports

Authored capability implementations can import only this closed host set. Any import outside the set fails instantiation before the implementation can run.

Host import	Description
`MemoryGet`	Read connector/capability memory.
`MemoryGetSnapshot`	Read a memory snapshot.
`MemoryPutIfAbsent`	Write memory only when absent.
`MemoryCompareExchange`	Atomic compare-and-exchange memory update.
`MemoryAppendJournal`	Append to a capability journal.
`MemoryAcquireLease`	Acquire a host-managed lease.
`MemoryReleaseLease`	Release a host-managed lease.
`MemoryDelete`	Delete host memory.
`MemoryExpire`	Set memory expiry.
`ObservabilityRecordSpan`	Record a structured span.
`ObservabilityLog`	Write a redacted observability log entry.
`SecretsSignRequest`	Sign a request without revealing raw secret material.
`SecretsHmac`	Compute HMAC without revealing raw secret material.
`SecretsAttachAuthToEgressPlan`	Attach auth to a host-validated egress plan.
`SecretsResolveRedactedMetadata`	Resolve redacted secret metadata only.
`SecretsDecryptForHostEgressOnly`	Decrypt only inside host egress boundary.
`EgressBuildPlan`	Build a governed egress plan.
`TimeNow`	Read host-provided current time.
`CapabilityAssert`	Assert a required capability grant at the host boundary.

Failure example

HTTP/1.1 403 Forbidden
{
  "error": {
    "code": "ACCESS_DENIED",
    "reasonCode": "ExposureBinding.RequiredGrantMissing",
    "bindingId": "mcp:Entity.Order.Delete",
    "missingGrants": ["entity:Order:delete"],
    "correlationId": "01HXZ0J4YV8AJF2GFG2T1F7Y42"
  }
}

Full surface atlas

Project capability surfaces