From 78234bc82ce7ea2c2717b1669946c4f8aa44ecc5 Mon Sep 17 00:00:00 2001 From: Sergii Demianchuk Date: Thu, 23 Jul 2026 21:39:24 -0400 Subject: [PATCH] test(levelcode): pin the 50% gross-margin invariant MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Answers "how do we verify the credit economics still hold the margin?" with something that runs on every change rather than a spreadsheet. The promise: model COGS stay at or below CREDIT_COGS_RATIO of subscription revenue, so gross margin is (1 - ratio) = 50% today, for ANY model mix. That holds because the budget is enforced in COST micro-$ while metering charges each model its real wire price — an expensive model burns the same dollar allowance faster, it cannot overspend it. Measured across every plan and every entitled model, spending the whole allowance on one model (the adversarial case, not an average): Pro $20 / Pro+ $40 / Max $60 / Ultra $100 -> 50.0% margin each worst single-model case on Ultra -> 50.0% (gpt-oss, kimi, opus, fable) Three specs: the per-plan COGS ceiling, the any-model-mix worst case, and that the credit allowance and the enforced cost budget stay two sides of one number (credits are retail = price; the budget is cost = price x ratio). If they ever drift, customers are either handed credits we do not fund or funded for credits they cannot spend. Denominating balances in credits was presentation only and did not move any of this — this spec is the standing proof, so a future change to pricing, the roster, the routing fee or the conversion fails here rather than in a P&L. Verified: 34 examples, 0 failures. Co-Authored-By: Claude Opus 4.8 --- spec/models/levelcode_plans_spec.rb | 46 +++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/spec/models/levelcode_plans_spec.rb b/spec/models/levelcode_plans_spec.rb index a7595aea..8d842eca 100644 --- a/spec/models/levelcode_plans_spec.rb +++ b/spec/models/levelcode_plans_spec.rb @@ -97,6 +97,52 @@ end end + describe 'gross margin (the economic invariant credits must not disturb)' do + # The business promise: model COGS stay at or below CREDIT_COGS_RATIO of subscription revenue, so + # gross margin is (1 - ratio) — 50% today — NO MATTER which models a customer picks. That holds + # because the budget is enforced in COST micro-$ while metering charges each model its real wire + # price: an expensive model burns the same dollar allowance faster, it does not overspend it. + # + # Denominating the customer's balance in CREDITS is presentation only and must never move this. This + # spec is the standing proof of that — if a future change to pricing, the roster, the routing fee or + # the credit conversion ever eats the margin, it fails here rather than in a monthly P&L. + it 'caps COGS at the target share of revenue for every plan' do + Levelcode::PLANS.each do |plan| + revenue = plan[:price_cents] / 100.0 + max_cogs = Levelcode.budget_micros(plan[:key]) / 1_000_000.0 + expect(max_cogs).to be <= (revenue * Levelcode::CREDIT_COGS_RATIO) + 0.005, + "#{plan[:name]}: enforced budget $#{max_cogs.round(2)} exceeds its COGS share" + margin = (revenue - max_cogs) / revenue + expect(margin).to be >= (1 - Levelcode::CREDIT_COGS_RATIO) - 0.001, + "#{plan[:name]}: margin #{(margin * 100).round(1)}% is under target" + end + end + + it 'holds for ANY model mix — the worst case is still at target' do + # Spending the entire allowance on the single priciest model is the adversarial case: if margin + # survives that, it survives every blend. Checked per model rather than on an average. + Levelcode::PLANS.each do |plan| + revenue = plan[:price_cents] / 100.0 + Levelcode.roster_for(plan[:key], Levelcode.budget_micros(plan[:key])).each do |m| + cogs = m[:turns_left] * Levelcode.per_turn_cost_micros(m[:id]) / 1_000_000.0 + margin = (revenue - cogs) / revenue + expect(margin).to be >= (1 - Levelcode::CREDIT_COGS_RATIO) - 0.001, + "#{plan[:name]} spent entirely on #{m[:id]}: margin #{(margin * 100).round(1)}%" + end + end + end + + it 'keeps the credit allowance and the COGS ceiling two sides of one number' do + # credits are retail (= price), the enforced budget is cost (= price x ratio). If those ever drift + # apart, customers are either given credits we do not fund or funded for credits they cannot spend. + Levelcode::PLANS.each do |plan| + credits_in_dollars = Levelcode.plan_credits(plan[:key]) / Levelcode::CREDITS_PER_DOLLAR.to_f + cost_budget = Levelcode.budget_micros(plan[:key]) / 1_000_000.0 + expect(cost_budget).to be_within(0.01).of(credits_in_dollars * Levelcode::CREDIT_COGS_RATIO) + end + end + end + describe '.plan' do it 'looks up a plan by key' do expect(Levelcode.plan('orbits_max')[:name]).to eq('Max')