# 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.