TorbatYar/docs/reference/extension-registry.md

Extension Registry

Contracts only. Products publish extensions; Core commercial owns the registry vocabulary.
Contract version: extension-registry.v1
Related: ADR-022 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_codes; they never ship extension payloads.