# Capability Registry

> **Contracts only.** Capabilities are independent, reusable objects.  
> ADR: [ADR-023](../architecture/adr/ADR-023.md) (v1.1)  
> Contract version: `capability-registry.v1`

---

## 1. Purpose

A **Capability** is a reusable commercial/technical ability that products **consume** or **provide**, and that Business Bundles **reference**.

Capabilities MUST be defined once in this registry. Products and bundles must not duplicate capability definitions.

---

## 2. CapabilityDefinition

| Field | Type | Meaning |
| --- | --- | --- |
| `capability_code` | string | Stable open key (e.g. `payments`, `appointments`) |
| `display_name` | string | |
| `description` | string | |
| `category` | string | Open (e.g. `commerce`, `ops`, `engage`, `content`, `infra`, `ai`) |
| `owner_hint` | string? | Typical owning service — **not** exclusive ownership lock |
| `status` | enum | `active` \| `reserved` \| `deprecated` |
| `related_feature_keys[]` | string[] | Optional L1/L3 feature key hints |
| `related_module_keys[]` | string[] | Optional |
| `ext` | object | Additive |

---

## 3. Illustrative capability matrix (examples — open registry)

| capability_code | Display | Category | Status |
| --- | --- | --- | --- |
| `payments` | Payments | commerce | active |
| `appointments` | Appointments | ops | reserved |
| `delivery` | Delivery / fleet | ops | active |
| `crm` | CRM | engage | active |
| `analytics` | Analytics | content | active |
| `forms` | Forms | content | active |
| `surveys` | Surveys | content | active |
| `wallet` | Wallet | commerce | reserved |
| `loyalty` | Loyalty | engage | active |
| `tickets` | Ticketing | ops | reserved |
| `courses` | Courses / learning | content | reserved |
| `storage` | File storage | infra | reserved |
| `notifications` | Notifications | engage | reserved |
| `sms` | SMS | engage | active |
| `email` | Email | engage | active |
| `voice` | Voice | engage | reserved |
| `maps` | Maps | infra | reserved |
| `qr` | QR | channel | reserved |
| `short-links` | Short links | channel | reserved |
| `printing` | Printing | ops | reserved |
| `ai` | AI | ai | reserved |

**Unlimited** additional capability codes MAY be registered without architecture changes.

---

## 4. Consumption rules

| Consumer | How it references capabilities |
| --- | --- |
| PlatformProduct | `PlatformProductCapability` → `capability_code` |
| BusinessBundle | `capability_refs[]` on bundle version |
| License / Entitlement | May gate via feature keys linked to capabilities |
| Recommendation | May emit capability codes in results |
| Extension | May require capabilities to load |

---

## 5. Invariants

1. One `capability_code` → one definition.
2. Products must not redefine capability semantics locally.
3. Bundles reference capabilities; they do not embed capability implementations.
4. Reserved capabilities document intent only — no engine authorization.