Implement boundary engine and close WP-0004

docs/BoundaryValidation.md

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