# Commercial Dependency Graph

> **Architecture / contracts only.**  
> Contract version: `commercial-dependency.v1`  
> Used by: Products, Capabilities, Bundles, Automation Packs, Extensions

---

## 1. Purpose

A unified **dependency graph** expresses relationships between commercial entities without embedding implementations.

---

## 2. Node kinds

| `node_kind` | Code space |
| --- | --- |
| `product` | `product_code` |
| `capability` | `capability_code` |
| `bundle` | `bundle_code` |
| `automation_pack` | `automation_pack_code` |
| `extension` | `extension_code` |
| `pricing_item` | `pricing_item_code` |
| `service` | `service_identifier` |

---

## 3. Edge — CommercialDependency

| Field | Type | Meaning |
| --- | --- | --- |
| `from_kind` / `from_code` | | Subject |
| `to_kind` / `to_code` | | Object |
| `relation` | DependencyRelation | See §4 |
| `strength` | enum? | `hard` \| `soft` |
| `reason` | string? | |
| `effective_from` / `effective_to` | datetime? | |

---

## 4. DependencyRelation

| Relation | Meaning |
| --- | --- |
| `requires` | Subject cannot activate without object |
| `optional` | Object may enhance subject |
| `conflicts` | Subject and object must not both be active |
| `recommended` | Soft suggestion (recommendations / UX) |
| `deprecated` | Subject should not be used; see replacement |
| `replacement` | Object replaces subject |

---

## 5. Illustrative dependency matrix (examples)

| From | Relation | To | Notes |
| --- | --- | --- | --- |
| `product.pay` | requires | capability `payments` | |
| `product.driver` | optional | capability `maps` | |
| `product.qr` | recommended | capability `short-links` | Future |
| `product.marketplace` | conflicts | *(none fixed)* | Independent |
| `bundle.restaurant.starter` | requires | `product.pay` | Via product ref |
| `bundle.restaurant.starter` | recommended | automation_pack `pack.order_sms` | Example |
| `product.short_link` | replacement | *(legacy link module if any)* | Future |
| `ext.pay.checkout_widget` | requires | `product.pay` | |
| `product.booking` | requires | capability `appointments` | Reserved |

---

## 6. Graph invariants

1. No cycles on `requires` edges (logical validation rule for future engines).
2. `conflicts` is symmetric when materialized.
3. `replacement` implies subject `deprecated` (recommended pairing).
4. Graph stores **references only** — no workflow or pricing amounts.
5. Unlimited nodes/edges via registry — architecture unchanged.