# Business Bundle Contracts

> **Documentation contract only.** No schema, API, or engine.  
> Architecture: [commercial-platform-architecture.md](../architecture/commercial-platform-architecture.md) · [ADR-023](../architecture/adr/ADR-023.md)  
> Contract version: `business-bundle.v1.1` (additive over `v1`)

---

## 1. Purpose

A **Business Bundle** is the platform commercial packaging unit. Bundles remain **lightweight**: they **reference** products, capabilities, automation packs, extensions, pricing, and (via subscription/license plans) commercial grants — they **never embed implementations**.

Legacy `services[]` / `modules[]` / `features[]` refs remain valid for compatibility with `commercial.v1` catalogs.

---

## 2. Aggregates

### 2.1 BusinessBundleDefinition

| Field | Type | Meaning |
| --- | --- | --- |
| `bundle_code` | string | Stable unique code (e.g. `bundle.restaurant.starter`) |
| `display_name` | string | Human label |
| `description` | string | Short commercial description |
| `owner` | string | Always `core-platform` for platform bundles |
| `status` | enum | `draft` \| `active` \| `deprecated` \| `retired` |
| `default_version` | string | Current `version_code` pointer |
| `metadata` | object | See BusinessBundleMetadata |
| `created_at` / `updated_at` | datetime | Audit (logical) |

### 2.2 BusinessBundleVersion

| Field | Type | Meaning |
| --- | --- | --- |
| `bundle_code` | string | Parent definition |
| `version_code` | string | Semver-like commercial version (e.g. `2026.07.1`) |
| `changelog` | string | Human notes |
| `product_refs[]` | BusinessBundleProductRef | **v1.1** PlatformProduct refs |
| `capability_refs[]` | BusinessBundleCapabilityRef | **v1.1** Capability Registry refs |
| `automation_pack_refs[]` | BusinessBundleAutomationPackRef | **v1.1** Automation Catalog refs |
| `extension_refs[]` | BusinessBundleExtensionRef | **v1.1** Extension Registry refs |
| `services[]` | BusinessBundleService | Legacy / complementary service refs |
| `modules[]` | BusinessBundleModule | Legacy module refs |
| `features[]` | BusinessBundleFeature | Legacy feature refs |
| `pricing_refs[]` | BusinessBundlePricingReference | Links to Pricing Catalog |
| `subscription_plan_refs[]` | string[] | **v1.1** Optional `plan_code`s |
| `license_policy_ref` | string? | **v1.1** Opaque license policy ref |
| `visibility` | BusinessBundleVisibility | Who may see/select |
| `lifecycle` | BusinessBundleLifecycle | Commercial lifecycle flags |
| `recommendation_rule_ids[]` | string[] | Optional rule links |
| `dependency_edge_ids[]` | string[] | Optional graph edge ids |
| `effective_from` / `effective_to` | datetime? | Window |

### 2.2a BusinessBundleProductRef (v1.1)

| Field | Type | Meaning |
| --- | --- | --- |
| `product_code` | string | PlatformProductRegistry entry |
| `required` | bool | |
| `min_version_code` | string? | |

### 2.2b BusinessBundleCapabilityRef (v1.1)

| Field | Type | Meaning |
| --- | --- | --- |
| `capability_code` | string | Capability Registry |
| `required` | bool | |

### 2.2c BusinessBundleAutomationPackRef (v1.1)

| Field | Type | Meaning |
| --- | --- | --- |
| `automation_pack_code` | string | Automation Catalog |
| `required` | bool | |

### 2.2d BusinessBundleExtensionRef (v1.1)

| Field | Type | Meaning |
| --- | --- | --- |
| `extension_code` | string | Extension Registry |
| `required` | bool | |

### 2.3 BusinessBundleService

| Field | Type | Meaning |
| --- | --- | --- |
| `service_identifier` | string | From service-manifest (e.g. `hospitality`, `payment`) |
| `required` | bool | Must be entitled for bundle activation |
| `service_bundle_refs[]` | string[] | Optional opaque L2 pack codes in owning service |
| `capability_prefix` | string? | Discovery hint only (prefer `capability_refs`) |

### 2.4 BusinessBundleModule

| Field | Type | Meaning |
| --- | --- | --- |
| `module_key` | string | Platform module key (e.g. `hospitality.menu`) |
| `service_identifier` | string | Owning service |
| `required` | bool | |

### 2.5 BusinessBundleFeature

| Field | Type | Meaning |
| --- | --- | --- |
| `feature_key` | string | Core L1 / service feature key (e.g. `payment.module.enabled`) |
| `service_identifier` | string | Owning service or `core-platform` |
| `required` | bool | |

### 2.6 BusinessBundlePricingReference

| Field | Type | Meaning |
| --- | --- | --- |
| `pricing_item_code` | string | FK-like ref to Pricing Catalog — **no amounts here** |
| `role` | enum | `primary` \| `addon` \| `enterprise_quote` \| `trial` |
| `billing_period_hint` | enum? | Informational only; catalog owns periods |

### 2.7 BusinessBundleRecommendationRule

Logical link only — full shape in [recommendation-contracts.md](recommendation-contracts.md).

| Field | Type | Meaning |
| --- | --- | --- |
| `rule_id` | string | |
| `bundle_code` | string | Target recommendation |
| `priority` | int | Higher wins among ties |
| `active` | bool | |

### 2.8 BusinessBundleVisibility

| Field | Type | Meaning |
| --- | --- | --- |
| `public_catalog` | bool | Visible on public onboarding |
| `admin_only` | bool | Platform admin catalog only |
| `tenant_tiers[]` | string[] | Optional tier gates |
| `business_type_codes[]` | string[] | Soft filter (recommendations still authoritative) |
| `regions[]` | string[] | Future regional visibility |
| `hidden` | bool | Completely hidden |

### 2.9 BusinessBundleLifecycle

| Field | Type | Meaning |
| --- | --- | --- |
| `sellable` | bool | New subscriptions allowed |
| `renewable` | bool | Existing may renew |
| `grandfathered` | bool | Existing keep access after deprecate |
| `replacement_bundle_code` | string? | Migration target |

### 2.10 BusinessBundleMetadata

| Field | Type | Meaning |
| --- | --- | --- |
| `tags[]` | string[] | Search tags |
| `locale_labels` | map | i18n labels |
| `icon_key` | string? | Design token / asset key |
| `sort_order` | int | Catalog order |
| `ext` | object | Additive reserved bag |

---

## 3. Invariants

1. A version MUST NOT store currency amounts, taxes, coupons, or discounts.
2. A version MUST NOT embed product/automation/extension implementations — **refs only**.
3. Prefer `product_refs` + `capability_refs` for new catalog entries; keep legacy service/module/feature refs for compatibility.
4. Deprecating a definition MUST NOT delete historical subscription refs (future storage).
5. Frontend MUST NOT invent bundle codes outside the canonical catalog.
6. Subscriptions and licenses are bound via plan/policy refs — bundles do not own subscription engines.

---

## 4. Relationship to Payment / Experience L2 packs

| Layer | Example | Owner |
| --- | --- | --- |
| Business Bundle | `bundle.restaurant.starter` | Core commercial |
| PlatformProduct | `product.pay` | Product Registry |
| Capability | `payments` | Capability Registry |
| Payment L2 | `payment.byo_psp.basic` | Payment |
| Experience L2 | (service pack codes) | Experience |

Business Bundle → product/capability/extension/automation refs → owning registries/services validate locally.