The Plane Capability Graph

The Plane Capability Graph (PCG) is Vadyl's canonical, tier-1 typed graph of everything a product backend can do — the resources, actions, triggers, measures, events, effects, policies, and transforms exposed by every plane. It is the truth that automations, agents, the dashboard graph explorer, and explainability reasoners read from.

Why a typed graph

Without a typed graph, cross-plane reasoning is brittle. An agent wanting to compose "when an Order is paid, send a receipt and update analytics" has to discover, by string-matching, what triggers exist, what actions are valid, what measures exist, and whether they connect. With the PCG, all of that is typed: missing edges fail closed, schema mismatches fail closed, unit incompatibilities fail closed — at compile time, not in production.

Resources, actions, triggers, measures

The PCG's core node kinds are typed by PlaneResourceKind (entities, surfaces, queues, MCP exposures, …), PlaneActionKind (read, write, invoke, publish, schedule, …), PlaneTriggerKind (entity event, schedule, webhook, signal, …), and PlaneMeasureKind(counters, latencies, gauges, business metrics).

Edges are typed too: PlaneEdgeKind covers triggers→actions, actions→effects, measures→events, transforms→measures, and the cross-plane relationships needed for typed reasoning.

Contributors

Every plane contributes to the PCG through narrow IPlaneCapabilityFacetContributor registrations. The Automation plane contributes its canonical effect / policy / transform / trigger vocabulary; the Agent plane contributes its skill / model / tool vocabulary; the Schema plane contributes per-entity action and event nodes; and so on.

This contribution model means adding a new plane (or a new capability within a plane) is a single registration — the PCG picks it up and every reasoner sees it.

Installed surfaces in the graph

Project-published and project-installed capability surfaces are graph citizens too. The PCG records the provider project, consumer project, published surface, installation, exposed operations, CLI commands, MCP tools, workflows, agent skills, event vocabularies, measures, triggers, grants, quota dimensions, billing attribution, and consumption records as typed nodes and edges.

This is what lets Vadyl answer questions like: which consumer projects depend on EmailService@1.2.0, which automations call itsemail.send operation, which CLI commands are exposed, which agent skills depend on it, which quotas apply, and which usages were billed to which project.

Runtime Fabric contribution

Runtime Fabric contributes workload pools, runtime substrates, runtime origins, autoscale targets, scale actions, lifecycle triggers, governance policies, and measures keyed by project, environment, surface, scale group, connector, and target. That is what lets automation, dashboard controls, agents, and explainability operate scaling as a typed project capability rather than as provider-specific dashboard state.

Autoscale rules can reference built-in runtime measures or custom PCG measures. A custom measure is valid only when its semantic unit, freshness window, dimensions, grants, and production sample source are compatible with the target being scaled.

Content-hashed compilation

The PCG is compiled once per content fingerprint. The fingerprint is a SHA-256 of the canonical-serialized contributor outputs. If your product model hasn't changed, the cached PCG is reused. On change, the compiler runs and the new graph is published through the canonical cache invalidation bus.

Acyclic by construction

The PCG compiler is forbidden from calling back into the contract projection compiler — projection consumes the graph, not the other way around. This is enforced at the type system level. Cycles are impossible because the dependency direction is one-way.

Cache invalidation

The PCG uses the canonical ICacheInvalidationBus with per-area distributed scopes. When a contributor's inputs change — a new entity is added, an automation is published, a new agent skill is registered — the PCG is recompiled and peer instances are notified. The compiled graph is fail-closed if any contributor fails: an invalid input doesn't produce a partial graph.

Who reads the PCG

• Automation compiler — type-checks declarative orchestrations against valid trigger / action / measure references.
• Agent planner — discovers what skills, tools, and actions are available for a project, with their typed signatures.
• Explainability projections — produce decision-record reasoning by referencing canonical PCG nodes.
• Dashboard graph explorer — renders the navigable view of a product backend's entire capability surface.
• Surface installer - validates publish/install impact, dependency edges, grant narrowing, and upgrade safety for project capability surfaces.