# Extension Registry

> **Contracts only.** Products publish extensions; Core commercial owns the registry vocabulary.  
> Contract version: `extension-registry.v1`  
> Related: [ADR-022](../architecture/adr/ADR-022.md) Published Actions / Embed (compatible, not duplicated)

---

## 1. Purpose

The **Extension Registry** lets every PlatformProduct publish reusable extension points without ownership conflicts.

Experience may *render* some extension kinds; owning products *execute* business logic.

---

## 2. Extension kinds (open registry)

| extension_kind | Meaning |
| --- | --- |
| `widget` | UI widget surface |
| `block` | Page/builder block |
| `action` | Invocable action (aligns with Published Action keys when public) |
| `embed` | Embeddable surface (aligns with embed contract when public) |
| `connector` | External system connector |
| `template` | Starter template |
| `report` | Report definition shell |
| `dashboard` | Dashboard shell |
| `theme` | Theme pack |
| `integration` | Integration pack |
| `validator` | Validation plugin |
| `automation_pack` | Ref to Automation Catalog pack |
| `ai_skill` | AI skill declaration |

Additional kinds MAY be registered without architecture changes.

---

## 3. ExtensionDefinition

| Field | Type | Meaning |
| --- | --- | --- |
| `extension_code` | string | Stable unique code |
| `extension_kind` | string | Open kind |
| `display_name` | string | |
| `publisher_product_code` | string | Publishing PlatformProduct |
| `owner_service_identifier` | string | Runtime owner |
| `required_capability_codes[]` | string[] | |
| `supported_surfaces[]` | string[] | Open (e.g. `admin`, `tenant`, `public`, `embed`) |
| `permission` | string? | |
| `feature_toggle` | string? | |
| `status` | enum | `draft` \| `active` \| `deprecated` |
| `documentation_ref` | string? | |
| `ext` | object | |

---

## 4. Ownership rules (no conflicts)

| Concern | Owner |
| --- | --- |
| Extension registry vocabulary | Core commercial (contracts) |
| Extension business execution | `owner_service_identifier` / publisher product |
| Public action/embed presentation | Experience (ADR-022) when surface is public |
| Commercial enablement | License / entitlement / visibility |

**Forbidden:** Experience owning another product’s connector logic; Marketplace absorbing unrelated extensions; bundles embedding extension implementations.

---

## 5. Illustrative extension matrix (examples)

| extension_code | Kind | Publisher (example) |
| --- | --- | --- |
| `ext.pay.checkout_widget` | widget | product.pay |
| `ext.crm.pipeline_block` | block | product.crm |
| `ext.pages.form_action` | action | product.pages |
| `ext.loyalty.card_embed` | embed | product.loyalty |
| `ext.driver.dispatch_connector` | connector | product.driver |
| `ext.accounting.invoice_template` | template | product.accounting |
| `ext.analytics.sales_report` | report | product.pages / analytics capability |
| `ext.hospitality.floor_dashboard` | dashboard | product.restaurant |
| `ext.experience.theme_pack` | theme | product.pages |
| `ext.comm.sms_validator` | validator | product.communication |
| `ext.pack.onboarding_sms` | automation_pack | *(pack ref, not product)* |
| `ext.ai.support_skill` | ai_skill | product.ai.* |

---

## 6. Invariants

1. Unlimited extensions via registry entries.
2. Extension codes must not collide across publishers (prefix by product recommended).
3. Bundles reference `extension_code`s; they never ship extension payloads.