Implement comparable LTV engine and close WP-0005

docs/ComparableCustomerLTV.md

@@ -0,0 +1,99 @@
+# Comparable Customer LTV
+
+Status: implementation-facing MVP for `ADAPTIVE-WP-0005`.
+
+## Purpose
+
+This document defines the first operational form of
+`average_comparable_customer_lifetime_value`.
+
+The goal is to compare pricing configurations using expected seller economics
+over time instead of only the current-period observatory snapshot.
+
+## Core Definition
+
+For the current MVP:
+
+`average_comparable_customer_lifetime_value`
+
+means discounted expected seller margin for a comparable customer profile over a
+finite horizon, minus acquisition and upfront seller investment costs.
+
+Inputs include:
+
+- validated monthly pricing economics from the boundary engine
+- comparable-customer usage expectations
+- churn and default risk assumptions
+- contract duration and commitment protections
+- seller acquisition and upfront investment costs
+- a seller-configurable discount rate and required-improvement factor
+
+## Reference Model Selection
+
+The comparison engine selects:
+
+`most_favorable_predefined_model`
+
+as the highest-LTV valid predefined model available to the comparable-customer
+profile. If no valid model exists, it falls back to the highest-LTV eligible
+predefined model so the comparison still produces an inspectable anchor.
+
+Eligibility is currently supplied by the simulation profile rather than derived
+solely from model metadata.
+
+## Required Improvement Semantics
+
+For non-reference configurations:
+
+```text
+average_comparable_customer_lifetime_value(candidate)
+>= average_comparable_customer_lifetime_value(reference)
+   × required_improvement_factor
+```
+
+When the reference LTV is positive, the threshold is multiplicative.
+
+When the reference LTV is negative, the engine switches to additive improvement
+semantics so the candidate must become less negative by the requested
+percentage. This avoids the invalid outcome where multiplying a negative value
+would reward a worse configuration.
+
+## Risk Model
+
+Current risk handling is intentionally simple and explicit:
+
+- monthly churn risk applies after committed months expire
+- monthly default risk applies throughout the horizon
+- prepayment and guaranteed-fee commitments reduce default exposure
+- reduced cancellation flexibility lowers modeled churn exposure
+
+This is a policy approximation, not a retention model trained from history.
+
+## Sensitivity Model
+
+Each comparison runs the base case plus named sensitivity cases. The current
+Coulomb adapter includes:
+
+- usage downside
+- usage upside
+- risk spike
+
+Sensitivity output reports:
+
+- scenario LTV
+- delta versus base LTV
+- whether the configuration remains accepted, approval-only, or rejected
+
+## Coulomb Calibration
+
+The Coulomb observatory currently calibrates the generic engine with:
+
+- observed payment-fee rate from `payment_records.json`
+- observed AI usage unit cost from `usage_records.json`
+- segment profiles from `ltv_scenarios.json`
+- profile-specific fixed-cost allocation overrides for comparable future
+  customers
+
+Those fixed-cost overrides are deliberate: the current single-member pilot cost
+structure is too distorted to act as a reusable comparable-customer baseline on
+its own.