# profitability-scenarios-v1

One pure ES module is shared by the website and downloadable CLI. It has no network/storage side effects. Inputs use JSON numeric values or decimal strings; arithmetic is IEEE-754 with presentation rounding, not an accounting ledger. Monetary inputs are bounded to 1e12; results must remain finite and below 1e15. Validate source amounts separately; do not use this planning engine for ledger posting.

Envelope: method, model (ecommerce/leads/saas), mode (assumptions/mixed/observed), currency (one ISO code), period (YYYY-MM), costMode (margin/itemized), includesVat (boolean), leadMode (budget/fixed), fields and scenarios. Every active field is {value,kind,source,period}. Kinds: observed, client_reported, derived, estimated, unknown. Unknown/null required inputs return incomplete. Observed mode refuses estimated or client-reported inputs. Derived fields still need source evidence; the engine does not verify declarations.

Templates demonstrate all required fields. VAT is explicitly supplied; monetary revenue inputs are divided by 1 + vatRate/100 only if includesVat. Enter costs and spend on the same net/recoverable-tax basis. Currency selection never performs FX. Customer value for leads must already deduct expected refunds; ecommerce uses refundPct. Margin is the share remaining after ALL direct product/service, shipping, payment and expected refund costs. Itemized mode instead subtracts one total direct-cost allocation; never use both or count a cost twice. Opex is excluded. marketingCost covers only declared acquisition/marketing costs, not every software or payroll cost.

## Ecommerce

Revenue = orders × AOV × (1 − refundPct/100), normalized for tax.
Contribution before marketing = revenue × margin, OR revenue − directCosts.
Contribution = contribution before marketing − adSpend − marketingCost.
Orders are not unique customers: acquisition CAC is unavailable without a verified new-customer denominator.

## Leads

Budget mode: leads = adSpend / CPL; positive spend with zero CPL is invalid. Fixed mode uses provided leads; changing budget alone does not invent extra leads. Expected customers = leads × conversionPct/100; fractional expected counts remain fractional in calculations.
Revenue = expected customers × customerValue (tax-normalized). customerValue is revenue after expected refunds within the explicit valueMonths window. This is the value of ONE acquisition-month cohort, not monthly cash. Itemized directCosts means total delivery costs across that cohort's entire value window, while media and marketing refer to that acquisition month. No automatic continuation-rate multiplier.
Media CAC = media / expected customers; marketing CAC = (media + declared marketing) / expected customers. No customers means unavailable, never a fabricated denominator of one.
With margin basis, budget mode holds media budget fixed: break-even CPL = media × conversion × value × margin / (media + other marketing). Fixed-lead mode instead uses max(0, conversion × value × margin − other marketing / leads), interpreting CPL as a unit acquisition-cost ceiling at that fixed volume. Conversion target = total marketing / (leads × value × margin). An infeasible CPL target is null: in budget mode media, conversion and unit contribution must be positive; in fixed-lead mode a negative cost ceiling means even free leads cannot cover the other marketing costs. A target above 100% is unattainable under the assumptions. Itemized mode omits these unit targets because cost scaling is unknown.

## SaaS

Opening MRR is retained as an observed/input snapshot. For EACH forward month:
closing MRR = opening MRR − opening MRR × revenue churn + opening MRR × expansion + newCustomers × ARPA.
Next month's opening equals the prior closing. New customers recur each month. As a simplified explicit billing assumption, each month uses closing MRR as revenue; real proration, annual prepayments and cash timing are not modeled. Monthly costs and marketing recur. Forecast revenue is the SUM of monthly rows; exit ARR = final MRR × 12, a run-rate rather than forecast annual revenue. Horizon is 1–120 months; no seasonality or automatic response curve.
Simple payback = marketing CAC / (ARPA × margin), in months; unavailable for zero customers/margin or itemized costs. It excludes retention effects and is not proof that the acquisition cost will be recovered. Logo churn is not accepted as revenue churn without explicit reviewed conversion.

## Shared interpretation

Revenue/media = total modeled revenue divided by media (not attributed ROAS).
Contribution return on marketing = contribution after direct costs and marketing divided by total included marketing; not a causal/incremental ROMI claim.
Break-even revenue with margin basis = total included marketing / margin. Zero margin: unavailable. Itemized basis = fixed direct costs + marketing, valid only while those costs remain fixed. SaaS target uses the full horizon. Zero denominator returns null. Break-even equals zero contribution, not a recommendation.

Scenarios require name, rationale and active-field overrides. Keep period, horizon and tax basis fixed across comparisons. Overrides are assumptions and never rewrite the input snapshot. Sensitivity increases each selected driver by 10% RELATIVE, holding others fixed. It is neither a probability interval nor a causal model. Show a change in percentage points separately from relative percentage change.
