Capabilities

The unit of work in SysMARA: every action your system can perform is a capability

What are Capabilities?

A capability is a named operation that your system can perform. Creating a user, generating an invoice, transferring workspace ownership — each is a capability. Capabilities are the central organizing concept in SysMARA: they connect entities (what data is involved), policies (who can do it), invariants (what rules must hold), and modules (where it lives).

Capabilities are declared in YAML and compiled into route handlers, test scaffolds, and metadata by the Capability Compiler. They are the primary unit the Change Protocol reasons about when computing impact surfaces and risk levels.

CapabilitySpec Structure

interface CapabilitySpec {
  name: string;           // unique capability name, e.g. "create_user"
  description: string;    // what this capability does
  module: string;         // owning module, e.g. "users"
  entities: string[];     // entity names this capability reads/writes
  input: CapabilityField[];   // typed input fields
  output: CapabilityField[];  // typed output fields
  policies: string[];     // policy names that gate this capability
  invariants: string[];   // invariant names checked during execution
  sideEffects?: string[]; // external effects (e.g. send_email, charge_card)
  idempotent?: boolean;   // whether the capability is safe to retry
}

CapabilityField

interface CapabilityField {
  name: string;
  type: string;          // string, number, boolean, date, etc.
  required: boolean;
  description?: string;
}

Connecting to Entities

The entities array declares which domain objects this capability reads or writes. Each entry creates a uses_entity edge in the AI System Graph. This is how the framework knows that modifying the subscription entity will affect the create_subscription, cancel_subscription, and upgrade_subscription capabilities.

Policy Gates

The policies array lists which access control policies govern this capability. Each creates a governed_by edge. At runtime, the policy engine evaluates all governing policies before executing the capability. If no policy grants access, the capability is denied.

Invariant Checks

The invariants array lists which business rules must hold when this capability executes. Each creates a protects edge from the invariant to the capability. The invariant engine checks these rules either at compile time, runtime, or both, depending on the invariant's enforcement mode.

Side Effects and Idempotency

The optional sideEffects array declares external effects like sending emails or charging credit cards. These are not validated by the framework but serve as documentation for AI agents and the Change Protocol. The idempotent flag tells the framework and AI agents whether it is safe to retry this capability without unwanted duplicate effects.

YAML Example: SaaS Billing

Here is the create_subscription capability from the SaaS billing example:

capabilities:
  - name: create_subscription
    description: Create a new billing subscription for a workspace
    module: billing
    entities:
      - subscription
      - workspace
    input:
      - name: workspace_id
        type: string
        required: true
        description: Workspace to attach the subscription to
      - name: plan
        type: string
        required: true
        description: Subscription plan (free, pro, enterprise)
      - name: billing_cycle
        type: string
        required: true
        description: Billing cycle (monthly, yearly)
    output:
      - name: subscription
        type: subscription
        required: true
        description: The created subscription entity
    policies:
      - admin_full_access
      - workspace_owner_manage
      - billing_admin_manage_subscriptions
    invariants:
      - subscription_must_have_workspace
      - no_duplicate_active_subscription

This declaration tells the framework (and any AI agent) everything it needs to know:

What the Compiler Does With Capabilities

The Capability Compiler processes each capability spec and generates three files:

  1. Route handler at routes/{name}.ts — A typed handler function with {Name}Input and {Name}Output interfaces generated from the input/output fields. Edit zone: generated.
  2. Test scaffold at tests/{name}.test.ts — Test stubs for the capability itself, each of its policies, and each of its invariants. Edit zone: editable.
  3. Metadata JSON at metadata/{name}.json — Resolved metadata with full entity, policy, and invariant details. Edit zone: generated.

Graph Relationships

A single capability creates multiple edges in the AI System Graph:

AI-Safe Change Workflows

Capabilities are the primary unit of change in the Change Protocol. Every change plan is structured around capability-level changes: adding, modifying, removing, or renaming capabilities. When an AI agent proposes to add a new capability, the Change Protocol checks which module it belongs to, whether the module's boundary rules allow access to the referenced entities, and whether the new policies and invariants it requires exist. When a capability is modified, the graph traces all downstream effects: which routes expose it, which flows include it as a step, which tests cover it, and which generated files reference it.