TorbatYar/docs/reference/capability-registry.md

Capability Registry

Contracts only. Capabilities are independent, reusable objects.
ADR: ADR-023 (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.