Make ProductVariant the sellable unit (Product as aggregate)

[juliuskrah]

Summary

The current implementation assumes Product is the sellable item. We need to make ProductVariant the sellable unit, with Product acting as the parent/aggregate that defines shared merchandising data and option structure.

This aligns runtime behavior with the resource model introduced in #77 (Product) and #83 (ProductVariant).

Scope

In scope:

• Make sellable item semantics variant-first across catalog/business flows
• Treat Product as a non-sellable parent descriptor and ProductVariant as the purchasable SKU
• Update read models and API contracts so price/inventory/sku come from variant-level data
• Ensure variant selection is required before add-to-cart/checkout operations
• Define how product-level computed fields (e.g. price range, total inventory) are derived from variants
• Update docs to explicitly state Product vs ProductVariant responsibilities

Out of scope:

• New pricing strategy engine
• New inventory reservation algorithms
• UI redesign beyond required API/contract behavior

Implementation Notes

Product and ProductVariant have different responsibilities in the data model. Product should describe a family of offerings (title, category, options, shared media), while ProductVariant represents a concrete sellable configuration with a distinct SKU, price, and stock state.

Keeping Product sellable creates ambiguity in inventory and pricing semantics, breaks option consistency, and undermines the intent of #83. This ticket standardizes the commerce contract so downstream systems (cart, checkout, promotions, inventory) all target the same sellable primitive.

Acceptance Criteria

• API/model semantics define ProductVariant as the only sellable unit
• Add-to-cart and checkout paths require/accept variant identity rather than product identity
• Inventory and pricing resolution are variant-based
• Product-level price/inventory aggregates are computed from variants and documented
• Validation rejects sellable flows that reference only a Product without a concrete variant
• Documentation reflects the Product (aggregate) vs ProductVariant (sellable) split
• Migration/compatibility note exists for any existing product-as-sellable assumptions

Dependencies

• Depends on: Support Kubernetes-style Product frontmatter #77 (Support Kubernetes-style Product frontmatter)
• Depends on: Support Kubernetes-style ProductVariant frontmatter #83 (Support Kubernetes-style ProductVariant frontmatter)
• Related: [Initiative] Catalog Validation in gitstore-api #105 (Catalog Validation in gitstore-api), [Initiative] Separate Markdown Parsing Layer from Catalog Validation #134 (Separate Markdown Parsing Layer from Catalog Validation)

Tracking

• Parent: [Initiative] Kubernetes-style Catalog Frontmatter #40
• Area: catalog
• Priority: p1 – critical
• Target Milestone / Release: TBD