Implement boundary engine and close WP-0004

projects/coulomb-pricing/observatory/api.py

@@ -20,6 +20,7 @@ from .load import (
     load_value_range,
 )
 from .allocation import build_cost_allocation
+from .boundary import build_boundary_validation
 from .credits import build_credit_summary, load_credit_wallets
 from .membership_analytics import build_membership_analytics
 from .pricing_context import build_cost_floor, build_market_price_view, build_value_range_view
@@ -93,6 +94,7 @@ def build_dashboard_payload(data_dir: Path | None = None, period: str | None = N
     cost_allocation = build_cost_allocation(snapshot, usage_records)
     ai_cost_per_member = usage_summary["cost_per_active_user_eur"]
     simulations = build_pricing_simulations(snapshot, models, ai_cost_per_member)
+    boundary_validation = build_boundary_validation(snapshot, models, usage_records)
     credit_wallets = load_credit_wallets(root)
     credit_summary = build_credit_summary(
         credit_wallets,
@@ -125,6 +127,7 @@ def build_dashboard_payload(data_dir: Path | None = None, period: str | None = N
             "usage": usage_summary,
             "cost_allocation": cost_allocation,
             "pricing_simulations": simulations,
+            "boundary_validation": boundary_validation,
             "credit_wallets": credit_summary,
             "recommendations": recommendations,
             "infrastructure": {

projects/coulomb-pricing/observatory/boundary.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from .models import EconomicsSnapshot, PricingModel
+
+from ._repo_root import ensure_repo_root_on_syspath
+
+ensure_repo_root_on_syspath()
+
+from adaptive_pricing_core.boundary_engine import (  # noqa: E402
+    BoundaryPolicy,
+    PricingConfiguration,
+    validate_pricing_configuration,
+)
+
+
+def _usage_unit_cost(records: list[dict[str, Any]], period: str) -> Decimal:
+    period_rows = [row for row in records if row.get("period") == period]
+    total_tokens = sum(Decimal(str(row.get("tokens", "0"))) for row in period_rows)
+    total_cost = sum(Decimal(str(row.get("cost_eur", "0"))) for row in period_rows)
+    if total_tokens <= Decimal("0"):
+        return Decimal("0")
+    return total_cost / total_tokens
+
+
+def _total_usage_units(records: list[dict[str, Any]], period: str) -> Decimal:
+    return sum(Decimal(str(row.get("tokens", "0"))) for row in records if row.get("period") == period)
+
+
+def build_boundary_policy(snapshot: EconomicsSnapshot) -> BoundaryPolicy:
+    return BoundaryPolicy(
+        minimum_margin_pct=Decimal("0"),
+        target_margin_pct=Decimal("15"),
+        max_payment_fee_pct=Decimal("10"),
+        max_expected_usage_variance_pct=Decimal("50"),
+        approval_discount_pct=Decimal("10"),
+        max_discount_pct=Decimal("25"),
+        minimum_contract_duration_for_discount_months=3,
+        minimum_turnover_multiple_for_discount=Decimal("1"),
+        minimum_prepayment_months_for_discount=Decimal("1"),
+    )
+
+
+def build_boundary_validation(
+    snapshot: EconomicsSnapshot,
+    models: list[PricingModel],
+    usage_records: list[dict[str, Any]],
+    segment: str | None = None,
+) -> dict[str, Any]:
+    fee_rate_pct = Decimal("0")
+    if snapshot.monthly_revenue > Decimal("0"):
+        fee_rate_pct = (
+            snapshot.monthly_payment_processing_cost / snapshot.monthly_revenue
+        ) * Decimal("100")
+
+    unit_cost = _usage_unit_cost(usage_records, snapshot.period)
+    usage_units = _total_usage_units(usage_records, snapshot.period)
+    direct_usage_cost = sum(
+        Decimal(str(row.get("cost_eur", "0")))
+        for row in usage_records
+        if row.get("period") == snapshot.period
+    )
+    allocated_fixed_cost = (
+        snapshot.monthly_infrastructure_cost / snapshot.active_members
+        if snapshot.active_members
+        else snapshot.monthly_infrastructure_cost
+    )
+
+    policy = build_boundary_policy(snapshot)
+    model_results = []
+    for model in models:
+        has_usage_component = any(component.kind == "usage" for component in model.charge_components)
+        configuration = PricingConfiguration(
+            model=model,
+            segment=segment or (model.eligibility[0] if model.eligibility else None),
+            expected_usage_units=usage_units if has_usage_component else Decimal("0"),
+            expected_usage_variance_pct=Decimal("25"),
+            allocated_fixed_cost=allocated_fixed_cost,
+            direct_cost_amount=Decimal("0") if has_usage_component else direct_usage_cost,
+            unit_cost=unit_cost if has_usage_component else Decimal("0"),
+            payment_fee_rate_pct=fee_rate_pct,
+        )
+        model_results.append(validate_pricing_configuration(configuration, policy))
+
+    return {
+        "period": snapshot.period,
+        "policy": policy,
+        "assumptions": {
+            "segment": segment or "model-default-eligibility",
+            "observed_usage_units": usage_units,
+            "observed_usage_unit_cost": unit_cost,
+            "direct_usage_cost_for_flat_models": direct_usage_cost,
+            "allocated_fixed_cost_per_member": allocated_fixed_cost,
+            "payment_fee_rate_pct": fee_rate_pct,
+            "expected_usage_variance_pct": Decimal("25"),
+        },
+        "model_results": model_results,
+        "notes": [
+            "This MVP policy uses current observatory economics and conservative defaults rather than a seller-specific governance file.",
+            "Self-serve discounts above 10% require approval; discounts above 25% are rejected.",
+            "Term-only concessions require at least a 3-month contract to count as meaningful commitment support.",
+        ],
+    }