Capability surfaces

A capability surface is Vadyl's canonical unit for something that can be described, bound, projected, authorized, invoked, observed, and explained. It covers pluggable infrastructure, but it is broader than provider wiring: projection surfaces, command surfaces, MCP tool surfaces, event vocabularies, workflows, agent skills, analytics measures, auth schemes, runtime handlers, storage/cache/ distribution policy, and installable project surfaces all use the same contract discipline.

The taxonomy is closed at the platform level. Projects author instances, bindings, manifests, implementations, and published slices inside that taxonomy. This keeps extension powerful without creating a second authority model beside Vadyl.

Kinds and families

Vadyl organizes capability surfaces into families with spaced ordinal ranges so the product can grow without colliding with existing contracts:

• Substrate - governed connections, database infrastructure, runtime fabric, distribution, analytics, model inference, storage, cache, secrets.
• Projection - REST/OpenAPI/GraphQL/gRPC, operation projection, SDKs, CLI commands, MCP tools, dashboard actions.
• Operational - event vocabularies, realtime, webhooks, scheduling, triggers, workflows, automation actions, agent skills.
• Knowledge - corpora, embeddings, retrieval, immutable memory, RAG surfaces.
• Governance - quotas, billing meters, auth schemes, federated contracts, installable surfaces.
• Execution - authored runtimes, workflow engines, scheduled-task hosts, edge handlers.
• Cross-cutting - observability sinks, explainability, secret providers, key rings.

Three implementation sources

Every capability surface has the same first-class implementation sources, indistinguishable to consumers:

• Built-in native - a platform implementation shipped with Vadyl.
• Declarative bundle - a manifest interpreted by the canonical declarative engine.
• Authored component - a WebAssembly Component Model artifact built from project source and governed by WIT contracts.

All three flow through the same router, registry, binding lifecycle, conformance story, and observability path.

Project-scope parity

Capability surfaces are the contract layer that makes project-scope parity possible. If a safe Vadyl plane can be represented as a capability, a project can author and publish that plane as its own capability surface. A project can publish a CLI command surface, an agent skill surface, an analytics surface, a workflow surface, an event vocabulary, an auth scheme, a webhook topic, or an entity/operation slice through the same manifest and exposure binding pipeline.

The project-published version carries provider project, consumer project, branch, publication version, installation, grant set, billing attribution, quota dimensions, descriptor hash, and consumption evidence. Those records make the capability installable, governable, billable, observable, and explainable across project boundaries.

Capability declarations

Every surface declares what it needs through a typed CapabilityDeclaration. The compiler enforces that the consumer's intent is satisfied - fail-closed at compile time instead of drifting at runtime.

{
  "kind": "CommandSurface",
  "implementationSource": "AuthoredComponent",
  "capabilities": {
    "supportsStructuredOutput": true,
    "supportsJsonSchemaInput": true,
    "requiresProjectCapabilityGrant": true,
    "emitsConsumptionDescriptor": true
  }
}

Host imports

Authored Wasm components reach the host through a closed set of host import kinds across memory, observability, secrets, egress, time, and capability assertions. That is the entire interaction surface: no ad-hoc syscalls, no ambient I/O, no direct provider SDK side channel.

Binding lifecycle

A capability surface binds to platform or project scope through a capability binding. Bindings carry secret references, capability overrides, conformance evidence, grant requirements, observability hooks, and descriptor hashes. Project bindings inherit through the project hierarchy; closer ancestors win when policy allows overrides.

Why this matters

Capability surfaces are why Vadyl can swap a Postgres binding to MongoDB without product logic changing. The same contract is also why a project can publish a command group, workflow library, analytics pack, agent skill set, or event vocabulary and let another project install it without inventing custom SDKs, ad-hoc webhooks, one-off IAM, or a separate billing ledger.

For the product view, see Project capability surfaces. For the install/publish contract, see Project capability surfaces reference. For the AST language canonical surfaces compile against, see AST reference.