Reference

Project capability surfaces

Reference model for project-authored, project-published, project-installed capability surfaces across UCSA, PCG, SDK, CLI, API, MCP, governance, usage, and explainability.

Project capability surfaces are the reference shape behind project-scope parity. They let a project publish selected capability slices for other projects to install, while preserving the same projection, authorization, billing, observability, and explainability rules that Vadyl uses for first-party platform surfaces.

Core descriptors

Descriptor	Purpose
`ProjectCapabilitySurfaceManifest`	Provider-side signed surface contract and typed slice selection.
`ExposureBindingDescriptor`	Protocol-specific binding for REST, SDK, CLI, MCP, dashboard, realtime, webhook, and event projections.
`InstallationManifest`	Consumer-side version pin, grant narrowing, billing scope, environment policy, and lifecycle state.
`ProjectCapabilityGrant`	Authorizes installed slices and narrows access by actor, project, branch, environment, time, quota, and risk.
`ProjectCapabilityConsumptionDescriptor`	Append-only invocation evidence for billing, quotas, dependency impact, audit, and explainability.
`PlaneCapabilityGraphDescriptor`	Typed graph projection of provider, consumer, install, exposed operation, command, event, measure, trigger, and effect.

Manifest shape

project-capability-surface.manifest

export default defineProjectCapabilitySurface({
  name: "RevenueOps",
  version: "2.4.0",
  publisherProject: "acme/revenue-ops",
  slices: {
    entities: ["Invoice", "LedgerEntry"],
    operations: ["invoice.issue", "ledger.reconcile"],
    cliCommands: ["revenue.invoice", "revenue.reconcile"],
    workflows: ["closeAccountingPeriod"],
    agentSkills: ["explainRevenueVariance"],
    analyticsMeasures: ["netRevenue", "deferredRevenue"],
    dashboards: ["revenue-overview"],
    events: ["invoice.issued", "ledger.reconciled"],
    webhookTopics: ["invoice.payment_failed"],
    authSchemes: ["revenue-service-account"],
  },
  exposure: {
    protocols: ["Rest", "Sdk", "Cli", "Mcp", "Dashboard", "Webhook", "Realtime"],
    stability: "Stable",
    deprecationPolicy: { minimumWindow: "12mo" },
  },
  governance: {
    requiredGrants: ["surface:RevenueOps.install", "operation:ledger.reconcile"],
    quotaDimensions: ["surface", "operation", "consumerProject"],
    billingAttribution: "consumer-project",
  },
});

Publishable slices

Slice	Coverage
`entities`	Entity, relation, association-template, field policy, trigger, transition contracts
`operations`	Global or entity-bound actions with input/output/error/idempotency contracts
`cliCommands`	Project command groups, subcommands, flags, output contracts, exit-code mapping
`workflows`	Durable workflow starts, signals, queries, compensation, approval tasks
`agentSkills`	Skill descriptors, prompt contracts, tool grants, memory scope, model requirements
`analyticsMeasures`	Measures, metrics, dashboards, reports, materialization policies, lineage
`events`	Event vocabulary, subscription filters, realtime channels, webhook topics
`authSchemes`	OAuth/OIDC/SAML/API-key/service-account/public receiver schemes
`runtimeHandlers`	Core handlers, edge handlers, scheduled handlers, event consumers, management handlers
`substratePolicies`	Storage namespaces, cache policy, distribution publication, runtime topology intent

Lifecycle states

Object	States
`PublishedSurface`	Draft - Published - Deprecated - Revoked
`SurfaceInstallation`	Requested - Installed - Suspended - UpgradePending - Uninstalled
`SurfaceGrant`	Proposed - Active - Expiring - Expired - Revoked
`ConsumptionRecord`	Reserved - Accepted - Reconciled - Corrected

Projection obligations

Every publishable slice produces exposure bindings for the protocols it supports. A CLI command, MCP tool, SDK method, REST operation, webhook topic, realtime channel, dashboard action, or automation action must all point back to the same capability id and PCG node.

{
  "bindingId": "cli:RevenueOps.revenue.reconcile",
  "capabilityId": "surface:RevenueOps:operation:ledger.reconcile",
  "capabilityNodeId": "pcg:surface:RevenueOps:ledger.reconcile",
  "protocolKind": "Cli",
  "exposureShape": "Command",
  "routeOrName": "vadyl revenue reconcile",
  "requiredGrantSet": ["surface:RevenueOps.invoke", "operation:ledger.reconcile"],
  "installationId": "sinst_01J...",
  "descriptorHash": "sha256:..."
}

Consumer invocation evidence

Consumption records are required for every installed call. They make cross-project use observable and explainable without asking each protocol to invent its own metering story.

{
  "installationId": "sinst_01J...",
  "publisherProjectId": "acme/revenue-ops",
  "consumerProjectId": "acme/storefront",
  "capabilityId": "surface:RevenueOps:operation:ledger.reconcile",
  "protocolKind": "Cli",
  "actorId": "user:finops",
  "billingAttributionProjectId": "acme/storefront",
  "quotaDimensions": ["surface", "operation", "consumerProject"],
  "correlationId": "01J...",
  "reasonCodeBlock": "Surface.RevenueOps.Invoke"
}

Related references

Exposure bindings

Authentication