57 lines
1.9 KiB
Markdown
57 lines
1.9 KiB
Markdown
# 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.
|