TorbatYar/docs/reference/universal-reference-contracts.md

Universal Reference Contracts

Reference contracts only. Stable IDs for all commercial registry objects.
Contract version: universal-reference.v1

---

1. Purpose

Every Commercial Foundation registry object receives a stable universal ID so cross-registry references never depend on service-specific database identifiers.

---

2. RegistryObjectId

Field	Type	Meaning
registry_object_id	uuid	Globally unique within commercial domain
object_kind	string	Open kind — §3
stable_code	string?	Human-stable code (product_code, asset_code, …)
version_code	string?	When pinning a version
uri	string?	Logical URI form

Logical URI form (documentation)

commercial://{object_kind}/{registry_object_id}[@{version_code}]

Example: commercial://asset/3fa85f64-...@2026.07.1

---

3. Object kinds (open)

product · bundle · capability · extension · automation_pack · automation_type · asset · policy · metadata · pricing_item · subscription · subscription_plan · license · dependency_edge · (future)

---

4. UniversalReference

Field	Type	Meaning
ref	RegistryObjectId | uri string
relation	string?	Optional semantic (uses, installs, prices, …)

Used by bundles, products, policies, assets, activation payloads, and dependency edges.

---

5. Rules

1. No service-specific identifiers as commercial cross-refs (no Experience page_id, Payment internal PK, etc. as commercial SoT).
2. Services MAY map locally via opaque correlation tables — commercial contracts speak only registry_object_id / stable_code.
3. Aligns with ADR-022 publish_id for public surfaces; commercial refs remain distinct (commercial:// vs publish_id).
4. Unlimited references — architecture unchanged.