# Adaptive Pricing Implementation Roadmap

Status: draft, implementation-facing.

## Purpose

This roadmap translates the strategic goals in `INTENT.md` into an executable
implementation sequence for the current repository state.

The root research roadmap in `research/PricingResearchRoadmap.md` remains the
conceptual and research-first planning artifact. This document starts from the
current implementation reality: a Coulomb-specific economic observatory MVP
under `projects/coulomb-pricing/observatory/`.

## Current Baseline

The repository already provides:

- ledger-backed economics and liquidity tracking
- cost-floor, value-range, and market-context views
- file-based Stripe / Bubble / OpenRouter imports
- scenario comparison for a small set of candidate pricing models
- rules-based pricing recommendations
- a local dashboard API and UI

The repository does not yet provide:

- a canonical, generic pricing-model schema
- a validation engine for pricing constraints and commitments
- comparable customer LTV estimation
- a customer-tuning solver
- outbound payment-provider execution
- governance workflows for publishing and changing pricing

## Sequencing Principles

- Preserve the observatory MVP as a proving ground while extracting generic core logic.
- Build schema and validation before solver or provider execution.
- Keep the internal pricing model as the source of truth; execution adapters come later.
- Require explainability at each stage: validation, simulation, tuning, and publish.
- Convert repository planning into milestone workplans rather than one large umbrella plan.

## Milestones

| Milestone | Goal | Primary workplan | Dependencies | Exit signal |
| --- | --- | --- | --- | --- |
| M0 | Economic observatory baseline | `ADAPTIVE-WP-0002` | done | Coulomb ledger, dashboard, simulator, recommendations |
| M1 | Extract canonical pricing core and schema | `ADAPTIVE-WP-0003` | M0 | Generic schema and validator adopted by Coulomb data |
| M2 | Add boundary engine and explainable validation | `ADAPTIVE-WP-0004` | M1 | Pricing configurations are validated against explicit constraints |
| M3 | Upgrade economics to comparable-customer LTV and richer simulation | `ADAPTIVE-WP-0005` | M1, M2 | Simulations compare models using segment/risk-aware economics |
| M4 | Implement customer-tuning solver prototype | `ADAPTIVE-WP-0006` | M2, M3 | Tuned configurations can be proposed, evaluated, and explained |
| M5 | Add provider abstraction and Stripe publication flow | `ADAPTIVE-WP-0007` | M1, M2, M3 | Internal pricing definitions can publish Stripe artifacts safely |
| M6 | Add governance and recommendation workflows | `ADAPTIVE-WP-0008` | M4, M5 | Pricing changes become auditable, explainable, and operational |

## Milestone Details

### M1 — Canonical Pricing Core And Schema

Create a reusable pricing core that can represent more than the current
subscription-only observatory model. Expand beyond the current narrow
`PricingModel` structure to include charge components, commitments, tunable
parameters, eligibility, and provider-mapping metadata.

### M2 — Boundary Engine And Explainable Validation

Turn strategic boundary conditions into testable rules. A pricing configuration
must be accepted or rejected by explicit logic, not only by dashboard review.
This milestone defines hard and soft constraints, invalid-configuration reasons,
and commitment-backed discount semantics.

### M3 — Comparable Customer LTV And Richer Simulation

Extend the current period snapshot and fixed-assumption simulator into an engine
that can compare pricing configurations across customer segments, usage
forecasts, risk classes, and contract conditions. This is the economics core
needed by any seller-safe adaptive system.

### M4 — Customer-Tuning Solver Prototype

Expose a customer/seller configuration interface where selected parameters are
tunable and the solver adjusts the rest while preserving seller economics. This
milestone is the first actual realization of the adaptive-pricing thesis in
`INTENT.md`.

### M5 — Provider Abstraction And Stripe Publication

Add an outbound execution layer that maps internal pricing definitions to Stripe
artifacts. This is where the repo moves from observatory-only to operational
pricing infrastructure.

### M6 — Governance And Recommendation Workflows

Operationalize the engine with approval policies, publish/change workflows,
auditable recommendations, experiment guardrails, and customer-facing safe
tuning contracts.

## Workplan Set

- `ADAPTIVE-WP-0003` — Canonical pricing core and schema extraction
- `ADAPTIVE-WP-0004` — Boundary engine and explainable validation
- `ADAPTIVE-WP-0005` — Comparable customer LTV and simulation upgrade
- `ADAPTIVE-WP-0006` — Customer-tuning solver prototype
- `ADAPTIVE-WP-0007` — Provider abstraction and Stripe publication
- `ADAPTIVE-WP-0008` — Governance and recommendation workflows

## Near-Term Recommendation

Start with `ADAPTIVE-WP-0003`.

The current implementation bottleneck is not UI or provider execution. It is
the absence of a sufficiently expressive internal pricing model. Until that
schema exists, later milestones would hard-code MVP assumptions into layers that
should remain generic.