# Pricing Model Schema

Status: draft, implementation-facing.

## Purpose

This document defines the canonical pricing-model schema now used by the
repository runtime. It is the implementation companion to the conceptual
vocabulary in `research/PricingOntology.md`.

The schema is designed to:

- preserve compatibility with the Coulomb observatory MVP
- represent richer pricing structures than a single subscription amount
- support later validation, solver, and provider-publication milestones

## Model Shape

Each pricing model contains:

- identity and lifecycle metadata
- normalized recurring access-fee fields for compatibility
- explicit charge components
- commitments
- tunable parameters
- eligibility and provider hints
- free-form metadata for deployment-specific details

## Canonical Fields

```yaml
id: string
name: string
model_type: flat_subscription | hybrid_subscription_usage | ...
lifecycle_phase: exploration | introduction | growth | maturity | saturation | decline
currency: EUR | USD | ...
status: active | candidate | retired
description: string

# Compatibility fields derived from the access component when omitted
access_fee_amount: decimal
access_fee_cadence: monthly | annual | one_time | ...
included_usage: string | null
overage_meter: string | null

charge_components:
  - id: string
    kind: access | setup | usage | support | discount | risk_adjustment
    amount: decimal | null
    cadence: string | null
    meter: string | null
    unit: string | null
    unit_price: decimal | null
    included_units: decimal | null
    label: string | null
    billing_treatment: recurring | metered | included | one_time | ...
    metadata: {}

commitments:
  - id: string
    kind: minimum_turnover | contract_duration | prepayment | committed_usage | ...
    value: string
    unit: string | null
    description: string

tunable_parameters:
  - key: string
    parameter_class: fixed | seller_controlled | customer_tunable | calculated | constrained | provider
    data_type: string
    description: string
    default_value: string | null
    min_value: decimal | null
    max_value: decimal | null
    options: []

eligibility:
  - string

provider_hints: {}
metadata: {}
```

## Parameter Classes

- `fixed`: immutable in the selected model
- `seller_controlled`: adjustable only by the seller or internal workflow
- `customer_tunable`: intended to become solver-visible customer choice
- `calculated`: derived from other fields or economics
- `constrained`: externally set but bounded by validation rules
- `provider`: implementation-only parameter for execution backends

## Validation Rules

Current runtime validation enforces:

- model ids are unique
- charge component ids are unique within a model
- exactly one `access` charge component exists
- access components define amount and cadence
- usage components define a meter
- `hybrid_subscription_usage` models include a usage charge component
- tunable parameter keys are unique
- `customer_tunable` parameters declare bounds or enumerated options
- commitment ids are unique

## Transitional Compatibility

The Coulomb observatory still consumes `access_fee_amount`, `access_fee_cadence`,
`included_usage`, and `overage_meter`. The canonical loader back-fills these
from `charge_components` when the explicit top-level fields are omitted.

This keeps the current observatory stable while later milestones replace
hard-coded observatory assumptions with generic pricing-core behavior.