# Registry Versioning Contracts

> **Version contracts only.** Applies across Commercial Foundation registries.  
> Contract version: `registry-versioning.v1`

---

## 1. Purpose

All commercial registries support explicit versions so catalogs can evolve without breaking historical subscriptions, installs, or policy decisions.

---

## 2. Versioned kinds

| Registry object | Version field | Notes |
| --- | --- | --- |
| Products | `version_code` on PlatformProductVersion | |
| Bundles | `version_code` on BusinessBundleVersion | |
| Capabilities | optional `version_code` on CapabilityDefinition | Additive |
| Extensions | optional `version_code` | Additive |
| Assets | `version_code` + AssetVersion records | |
| Automation Packs | `version_code` | |
| Policies | `version_code` on PolicyDefinition | |
| Metadata | `version_code` on MetadataBag | |

---

## 3. RegistryVersionRecord (logical)

| Field | Type | Meaning |
| --- | --- | --- |
| `registry_object_id` | uuid | Version record id |
| `parent_id` | uuid | Versioned object id |
| `parent_kind` | string | product/bundle/asset/… |
| `version_code` | string | Opaque commercial version string |
| `changelog` | string? | |
| `status` | enum | `draft` \| `published` \| `deprecated` \| `retired` |
| `effective_from` / `effective_to` | datetime? | |
| `supersedes_version_code` | string? | |
| `content_snapshot_ref` | string? | Opaque |
| `ext` | object | |

---

## 4. Rules

1. Publishing a new version MUST NOT rewrite historical binding snapshots (future engines pin versions at subscribe/install time).
2. `version_code` is an open string (e.g. `2026.07.1`, semver-like) — not a forced semver parser in contracts.
3. Deprecation of a version is independent of parent object lifecycle.
4. Unlimited versions per object — architecture unchanged.