# Capabilities

A capability is the stable interface a project binds to. `rag.embedding@1` is a promise about input
and output shape and about semantics — not about which model, node or file satisfies it.

## Why this exists

Bind an application to a model and you have coupled it to a decision you will want to change: a
better model, a different quantisation, a different node. Every one of those becomes a
coordinated change across every consumer.

Bind it to a capability and the substitution is ModelForge's problem. That is why
[SYSTEM_ARCHITECTURE.md](architecture/SYSTEM_ARCHITECTURE.md) establishes that applications bind to capabilities and never to model
paths, and why nothing in the platform couples project code to a Hugging Face repository name.

## The pieces

| Concept | What it is |
| --- | --- |
| **Capability** | A named kind of work: `rag.embedding`, `document.ocr`, `vision.embedding` |
| **Capability contract** | A version of that capability with a fixed input and output schema |
| **Capability deployment** | A specific artifact set and runtime profile serving a contract |
| **Project binding** | A project's declaration that it uses a contract, on a channel |
| **Service client** | An application's credential, scoped to specific capabilities |

A contract has at most one `stable` deployment at a time. That is enforced by a partial unique index
in the database *and* asserted by a platform invariant — two layers, because the invariant is there
for the case where the guard has been bypassed.

## Contracts shipped with v1.0.0

| Capability | Version |
| --- | --- |
| `rag.embedding` | 1 |
| `rag.reranking` | 1 |
| `document.ocr` | 1 |
| `vision.embedding` | 1 |
| `speech.transcription` | 1 |
| `assistant.general` | 1 |
| `assistant.vision` | 1 |

A contract being defined in a manifest does **not** mean anything is serving it. A deployment
requires a model artifact acquired, verified and promoted through the lifecycle. A newly installed
control plane has contracts available to register and no deployments — see
[FIRST_RUN.md](FIRST_RUN.md).

## Channels

`stable`, `experimental` and the production flag are separate ideas. A project can bind to
`experimental` for a capability while another binds to `stable` for the same one, and a deployment
being production is an explicit, approved, audited state — `no_hidden_auto_promotion` asserts that
no production deployment exists without a recorded production approval.

## Upgrade classes

Every contract declares what a change to it means:

| Class | Meaning |
| --- | --- |
| compatible | The replacement can serve existing consumers unchanged |
| `requires_reindex` | The embedding space changed; existing vectors are not comparable |

`requires_reindex` is the one that cannot be waved through. A project binding must declare that it
supports reindex migration before it can bind such a contract, and the migration engine will not
swap an alias underneath data that has not been reindexed.

## Invoking

See [PROJECT_INTEGRATION.md](PROJECT_INTEGRATION.md).

## What a capability guarantees

- the input and output schema for its version;
- that only an approved, verified artifact is behind it;
- that a refusal is named — `NO_ELIGIBLE_NODE`, `CAPACITY_CONSTRAINED`, `CAPABILITY_NOT_AUTHORIZED` —
  rather than an answer built on something stale.

## What it does not guarantee

- which model answered, or that the same model answers next time;
- that a deployment exists at all, if nothing has been promoted;
- latency: that depends on the node, the model and current pressure. The gateway reports queue and
  inference time per request so you can see which is which.