feat(engine): pluggable SaaS pricing shapes — flat_subscription, per_unit_flat, free_tier, transactional (#241)

[elecnix]

Summary

Closes #241 by promoting the external-node extension point from a single transactional formula into a pluggable SaaS pricing-handler registry. Four built-in shapes cover the most common SaaS billing models; third-party packages add more via infra_cost_model.saas_handlers entry-points.

Design

Each shape is a (quantity, params) -> monthly_cost_usd callable. The model declares which shape a metric uses:

saas_vendor:
  provider: workos
  usageMetrics:
    MAU:             { unit: Users,  value: 0, shape: free_tier,       free: 1000000, overage: 0.01 }
    SSO-Connection:  { unit: Conns,  value: 0, shape: per_unit_flat,   rate: 125.0 }
    AuditLog-Org:    { unit: Orgs,   value: 0, shape: per_unit_flat,   rate: 5.0 }
    CustomDomain:    { unit: Months, value: 0, shape: flat_subscription, rate: 99.0 }

so free-tier boundaries and per-unit rates live in the model, not in Python.

Built-in shapes

Shape	Signature	Example
flat_subscription	quantity × rate ($/unit-mo), 0 = off	Custom domain, $99/mo
per_unit_flat	quantity × rate ($/unit-mo)	SSO connections, $125/conn-mo
free_tier	First free units at $0, then overage $/unit, optional stepped tiers	AuthKit, 1M MAU free, $0.01 above
transactional	volume × percentage + quantity × (fixed + per_call)	The existing Stripe/Twilio pattern

Engine integration

Both _compute_flat_cost and _compute_tiered_cost dispatch to SaaSPricingRegistry.compute() when a metric declares a shape field — before the catalog / embedded pricingRates fallback path. An unknown shape returns None instead of raising: backward-compatible by construction.

Entry-point discovery

discover_entry_point_handlers() scans infra_cost_model.saas_handlers at import time. The four built-in shapes themselves are registered as entry-points.

What this does NOT do

• Does not change the catalog or embedded pricingRates path (Principle 13).
• Does not register new catalog rows or AWS pricing data.
• Does not change the ExternalServiceRegistry API.
• Does not break the existing external tests — all 16 pass unchanged.

Tests

tests/test_saas_pricing_shapes.py — 32 new tests covering all shapes, registry, engine integration, backward compatibility, and entry-point discovery. All 51 external tests pass, zero regressions.

— silent-orca-64