Skip to content
Almathal Handbook

Capability

Accepted

A Capability is a declared, namespaced, versioned operation or feature that an Adapter or Module provides. Capabilities are the mechanism by which Slots in an Archetype match against Adapters and Modules in the libraries.

Capability Format

A Capability is identified by a namespaced slug with a mandatory version:

capability:<category>/<capability-name>/v<N>

Examples:

capability:persistence/transactions/v1
capability:persistence/pagination/v1
capability:auth/sso/v1
capability:auth/mfa/v1
capability:llm/streaming/v1
capability:llm/tool-use/v1
capability:vector-search/hybrid-retrieval/v1

The integer version (v1, v2) signals interface stability. Capabilities evolve in major versions only; there is no concept of a minor or patch change to a Capability.

Capabilities With Modes or Sub-fields

A Capability can have structured sub-information beyond its identity:

{
  "id": "capability:persistence/transactions/v1",
  "modes": ["jta", "local"]
}


{
  "id": "capability:persistence/pagination/v1",
  "styles": ["offset", "cursor"]
}


{
  "id": "capability:auth/token-issuance/v1",
  "token_types": ["jwt", "opaque"]
}

This lets Slots require not just “any Adapter with pagination” but “an Adapter with cursor-style pagination,” when the difference matters.

Where Capabilities Are Declared

In an Adapter or Module Manifest:

{
  "capabilities": [
    { "id": "capability:persistence/crud/v1" },
    { "id": "capability:persistence/transactions/v1", "modes": ["jta", "local"] },
    { "id": "capability:persistence/pagination/v1", "styles": ["offset", "cursor"] }
  ]
}

In an Archetype’s Slot declaration:

{
  "slot_id": "slot:rag-chatbot/persistence",
  "required_capabilities": [
    "capability:persistence/crud/v1",
    "capability:persistence/transactions/v1"
  ]
}

The Resolver matches required Capabilities to provided Capabilities during Spec Resolution.

Capability vs Contract

These are distinct concepts that often appear together. The distinction is important:

CapabilityContract
”This thing can do X""This thing looks like interface Y”
Feature declarationInterface shape
Required by a Slot to filter candidatesRequired by a Slot to ensure substitutability
Many Capabilities per AdapterOften one or few Contracts per Adapter

Two Adapters with the same Capability can have different Contracts (both support transactions but expose different APIs). Two Adapters with the same Contract are substitutable. A Slot typically requires both: a set of Capabilities and a Contract.

See Contract for the parallel concept.

The Capability Namespace

The list of valid Capability IDs is governed centrally. Adapter authors propose new Capabilities; the platform team (or an agent + human review process) admits them after evaluating:

  • Whether the proposed Capability is genuinely new (not a synonym for an existing one)
  • Whether the namespace fits (correct category, correct name shape)
  • Whether the semantics are well-defined enough to be implementable consistently

Once admitted, the Capability ID is fixed. Renaming requires an ADR.

Governance → Capability Namespace documents the registry and admission process in detail.

Why Capabilities Are Versioned

The same logical feature can change over time. capability:persistence/pagination/v1 might be limited to offset-based pagination. A v2 adds cursor-based pagination as a required mode (not optional). Adapters that only do offset pagination still match v1 but not v2.

This lets Archetypes evolve their requirements without invalidating existing Adapters: an Archetype updated to require v2 will reject Adapters that only declare v1, prompting a substitution.

The integer version makes the implication clear: every version bump is a breaking change in what’s required of providers. There are no compatible minor updates to interfaces.

Capability Lifecycle

Capabilities can be deprecated when their semantics become unclear or when a better-designed successor exists. Deprecation follows:

  1. Successor Capability is admitted (capability:.../v2, or a renamed Capability)
  2. Adapters declaring the deprecated Capability remain valid
  3. Archetypes are updated to require the successor
  4. After a transition period, the deprecated Capability is archived

Generated apps continue to resolve correctly throughout because the Manifest-recorded provided Capabilities never change for a given Adapter version.

Capability Discovery

Within the platform documentation, the canonical Capability list lives at Governance → Capability Namespace. Adapter and Module Manifest authors reference this list when declaring what their building block provides.

When drafting a new Adapter Manifest and finding no Capability that fits a feature the Adapter provides, the author proposes a new Capability through the governance process rather than declaring an ad-hoc identifier.