Implement canonical pricing core and close WP-0003

docs/PricingModelSchema.md

@@ -0,0 +1,113 @@
+# 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.