Business Bundle Contracts
Documentation contract only. No schema, API, or engine.
Architecture: commercial-platform-architecture.md · ADR-023
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_codes |
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.
| 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
- A version MUST NOT store currency amounts, taxes, coupons, or discounts.
- A version MUST NOT embed product/automation/extension implementations — refs only.
- Prefer
product_refs + capability_refs for new catalog entries; keep legacy service/module/feature refs for compatibility.
- Deprecating a definition MUST NOT delete historical subscription refs (future storage).
- Frontend MUST NOT invent bundle codes outside the canonical catalog.
- 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.
