generated from coulomb/repo-seed
79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# Boundary Validation
|
|
|
|
Status: implementation-facing MVP for `ADAPTIVE-WP-0004`.
|
|
|
|
## Purpose
|
|
|
|
This document describes the first explicit boundary engine now available in
|
|
`adaptive_pricing_core.boundary_engine`.
|
|
|
|
The engine turns pricing-policy intent into inspectable validation outcomes
|
|
instead of leaving viability checks implicit in dashboard review.
|
|
|
|
## Inputs
|
|
|
|
The validator accepts:
|
|
|
|
- a canonical `PricingModel`
|
|
- a `PricingConfiguration` describing expected usage, fee assumptions, cost
|
|
allocation, optional price overrides, and commitment terms
|
|
- a `BoundaryPolicy` defining hard and soft limits
|
|
|
|
## Constraint Types
|
|
|
|
Current MVP constraints cover:
|
|
|
|
- segment eligibility
|
|
- expected usage variance limit
|
|
- payment fee ceiling
|
|
- cost-floor coverage
|
|
- minimum margin
|
|
- target-margin approval threshold
|
|
- discount exposure ceiling
|
|
- discount approval threshold
|
|
- commitment-backed concession enforcement
|
|
|
|
Hard constraints reject a configuration. Soft constraints mark it as valid only
|
|
with approval.
|
|
|
|
## Commitment Logic
|
|
|
|
The engine treats a concession as any configuration that weakens seller
|
|
economics relative to the model baseline under the same scenario assumptions.
|
|
|
|
A concession is considered meaningfully backed only when at least one of these
|
|
protections is present:
|
|
|
|
- minimum monthly turnover at or above modeled monthly revenue
|
|
- prepayment covering at least one modeled month
|
|
- guaranteed platform fee at or above modeled monthly revenue
|
|
- customer-funded onboarding that neutralizes onboarding cost
|
|
- materially longer contract duration
|
|
- reduced cancellation flexibility
|
|
|
|
## Outputs
|
|
|
|
Validation returns a `ValidationResult` with:
|
|
|
|
- `decision`: `accepted`, `requires_approval`, or `rejected`
|
|
- `valid` and `requires_approval`
|
|
- a human-readable summary
|
|
- machine-readable configuration snapshot
|
|
- machine-readable economics metrics
|
|
- per-constraint results with reasons, thresholds, and suggested actions
|
|
|
|
## Coulomb Adapter
|
|
|
|
The Coulomb observatory exposes this engine through
|
|
`observatory.boundary.build_boundary_validation()`.
|
|
|
|
That adapter currently uses:
|
|
|
|
- observed per-period payment fee rate
|
|
- observed AI usage cost
|
|
- observed per-member infrastructure cost allocation
|
|
- conservative default policy thresholds
|
|
|
|
This is intentionally an MVP policy surface. Later milestones can replace these
|
|
defaults with seller-managed governance data and richer LTV-aware constraints.
|