fix: NPV bug

Author: piotrlangowski

mcp-server/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.2",
   "name": "sherpa",
   "display_name": "Sherpa — AI Feature ROI Calculator",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "description": "CFO-grade ROI for AI features in SaaS: cohort revenue model + LLM token costs → NPV, IRR, payback, TCO. 100% local.",
   "long_description": "Sherpa lets you model the business case for AI features conversationally. Define AI services with their token usage, group them into packs and pricing plans, model your customer base as cohorts, and ask Claude to build and compare ROI scenarios: net present value, internal rate of return, payback period, total cost of ownership and sensitivity (tornado) analysis. All data stays in a local SQLite database — nothing is sent to the cloud. On first run the extension creates a demo workspace so you can start asking questions immediately.",
   "author": {

mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sherpa-mcp-server",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "type": "module",
   "scripts": {
     "prebuild": "node ../scripts/gen-guidance.mjs",

mcp-server/src/index.ts

@@ -365,15 +365,17 @@ function getFullScenario(scenarioId: string): Scenario | null {
       SELECT id, name, vertical_id, current_users, monthly_acquisition,
              acquisition_growth_rate, monthly_churn_rate, retention_floor,
              monthly_expansion_rate, ai_adoption_rate, base_arpu,
-             arpu_uplift, arpu_uplift_percent, churn_reduction, acquisition_uplift
+             arpu_uplift, arpu_uplift_percent, churn_reduction, acquisition_uplift,
+             gross_margin, adoption_ramp_months
       FROM cohort_configs
     `).all() as any[];
   } else if (s.scope_type === 'verticals') {
     baseCohorts = db.prepare(`
       SELECT c.id, c.name, c.vertical_id, c.current_users, c.monthly_acquisition,
              c.acquisition_growth_rate, c.monthly_churn_rate, c.retention_floor,
              c.monthly_expansion_rate, c.ai_adoption_rate, c.base_arpu,
-             c.arpu_uplift, c.arpu_uplift_percent, c.churn_reduction, c.acquisition_uplift
+             c.arpu_uplift, c.arpu_uplift_percent, c.churn_reduction, c.acquisition_uplift,
+             c.gross_margin, c.adoption_ramp_months
       FROM cohort_configs c
       JOIN verticals v ON c.vertical_id = v.id
       JOIN scenario_verticals sv ON sv.vertical_id = v.id
@@ -385,7 +387,8 @@ function getFullScenario(scenarioId: string): Scenario | null {
       SELECT c.id, c.name, c.vertical_id, c.current_users, c.monthly_acquisition,
              c.acquisition_growth_rate, c.monthly_churn_rate, c.retention_floor,
              c.monthly_expansion_rate, c.ai_adoption_rate, c.base_arpu,
-             c.arpu_uplift, c.arpu_uplift_percent, c.churn_reduction, c.acquisition_uplift
+             c.arpu_uplift, c.arpu_uplift_percent, c.churn_reduction, c.acquisition_uplift,
+             c.gross_margin, c.adoption_ramp_months
       FROM cohort_configs c
       JOIN scenario_cohorts sc ON sc.cohort_config_id = c.id
       WHERE sc.scenario_id = ?
@@ -397,6 +400,7 @@ function getFullScenario(scenarioId: string): Scenario | null {
     SELECT id, scenario_id, target_type, target_id, monthly_churn_rate, monthly_acquisition,
            acquisition_growth_rate, ai_adoption_rate, retention_floor, expansion_rate, arpu_override,
            arpu_uplift, arpu_uplift_percent, churn_reduction, acquisition_uplift,
+           gross_margin, adoption_ramp_months,
            evc_extra_value_multiplier, evc_negative_value_multiplier, evc_nba_multiplier
     FROM scenario_scope_overrides
     WHERE scenario_id = ?
@@ -3270,9 +3274,11 @@ server.tool(
           if (scenario.modeling_type === 'incremental' || carrier === 'cohort') {
             throw new Error(`Monetization overrides are disabled for incremental or cohort-carrier scenarios.`);
           }
-          const expectedEntityType = carrier === 'feature' ? 'service' : carrier;
-          if (entityType !== expectedEntityType) {
-            throw new Error(`Monetization overrides for this scenario can only be set on '${expectedEntityType}' entities (since the resolved carrier is '${carrier}').`);
+          if (carrier !== 'composite') {
+            const expectedEntityType = carrier === 'feature' ? 'service' : carrier;
+            if (entityType !== expectedEntityType) {
+              throw new Error(`Monetization overrides for this scenario can only be set on '${expectedEntityType}' entities (since the resolved carrier is '${carrier}').`);
+            }
           }
         }
         if (monType === 'none') {

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "sherpa",
 	"private": true,
-	"version": "1.0.38",
+	"version": "1.0.39",
 	"type": "module",
 	"scripts": {
 		"dev": "vite dev",

src/lib/components/wizard/ScenarioWizard.svelte

@@ -133,6 +133,8 @@
     arpu_uplift_percent: number | null;
     churn_reduction: number | null;
     acquisition_uplift: number | null;
+    gross_margin: number | null;
+    adoption_ramp_months: number | null;
   };
   let overrides = $state<OverrideRow[]>([]);
   let openOverrides = $state<Record<string, boolean>>({});
@@ -147,7 +149,9 @@
     arpu_uplift: o.arpu_uplift !== null ? parseFloat(o.arpu_uplift as any) : null,
     arpu_uplift_percent: o.arpu_uplift_percent !== null ? o.arpu_uplift_percent / 100 : null,
     churn_reduction: o.churn_reduction !== null ? o.churn_reduction / 100 : null,
-    acquisition_uplift: o.acquisition_uplift !== null ? o.acquisition_uplift / 100 : null
+    acquisition_uplift: o.acquisition_uplift !== null ? o.acquisition_uplift / 100 : null,
+    gross_margin: o.gross_margin !== null ? o.gross_margin / 100 : null,
+    adoption_ramp_months: o.adoption_ramp_months !== null ? parseInt(o.adoption_ramp_months as any) : null
   }))));
 
   // Sync overrides structure to selection
@@ -164,7 +168,8 @@
           target_type: 'all_clients', target_id: 'all', name: 'Global Client Base',
           monthly_churn_rate: null, monthly_acquisition: null, acquisition_growth_rate: null,
           ai_adoption_rate: null, retention_floor: null, expansion_rate: null, arpu_override: null,
-          arpu_uplift: null, arpu_uplift_percent: null, churn_reduction: null, acquisition_uplift: null
+          arpu_uplift: null, arpu_uplift_percent: null, churn_reduction: null, acquisition_uplift: null,
+          gross_margin: null, adoption_ramp_months: null
         });
       } else if (_scopeType === 'cohorts') {
         for (const c of data.cohorts) {
@@ -174,7 +179,8 @@
               target_type: 'cohort', target_id: c.id, name: c.name,
               monthly_churn_rate: null, monthly_acquisition: null, acquisition_growth_rate: null,
               ai_adoption_rate: null, retention_floor: null, expansion_rate: null, arpu_override: null,
-              arpu_uplift: null, arpu_uplift_percent: null, churn_reduction: null, acquisition_uplift: null
+              arpu_uplift: null, arpu_uplift_percent: null, churn_reduction: null, acquisition_uplift: null,
+              gross_margin: null, adoption_ramp_months: null
             });
           }
         }
@@ -311,7 +317,9 @@
             arpu_uplift: ov.arpu_uplift,
             arpu_uplift_percent: ov.arpu_uplift_percent !== null ? Math.round(ov.arpu_uplift_percent * 1000) / 10 : null,
             churn_reduction: ov.churn_reduction !== null ? Math.round(ov.churn_reduction * 1000) / 10 : null,
-            acquisition_uplift: ov.acquisition_uplift !== null ? Math.round(ov.acquisition_uplift * 1000) / 10 : null
+            acquisition_uplift: ov.acquisition_uplift !== null ? Math.round(ov.acquisition_uplift * 1000) / 10 : null,
+            gross_margin: ov.gross_margin !== null && ov.gross_margin !== undefined ? ov.gross_margin * 100 : null,
+            adoption_ramp_months: ov.adoption_ramp_months ?? null
           };
         });
       } else {
@@ -369,7 +377,9 @@
       arpu_uplift: o.arpu_uplift !== null ? parseFloat(o.arpu_uplift as any) : null,
       arpu_uplift_percent: o.arpu_uplift_percent !== null ? o.arpu_uplift_percent / 100 : null,
       churn_reduction: o.churn_reduction !== null ? o.churn_reduction / 100 : null,
-      acquisition_uplift: o.acquisition_uplift !== null ? o.acquisition_uplift / 100 : null
+      acquisition_uplift: o.acquisition_uplift !== null ? o.acquisition_uplift / 100 : null,
+      gross_margin: o.gross_margin !== null ? o.gross_margin / 100 : null,
+      adoption_ramp_months: o.adoption_ramp_months !== null ? parseInt(o.adoption_ramp_months as any) : null
     }));
     return resolveScenarioCohortsClient(scopeType, data.cohorts, selectedCohorts, formattedOverrides as any[]);
   });
@@ -385,7 +395,9 @@
       arpu_uplift: o.arpu_uplift !== null ? parseFloat(o.arpu_uplift as any) : null,
       arpu_uplift_percent: o.arpu_uplift_percent !== null ? o.arpu_uplift_percent / 100 : null,
       churn_reduction: o.churn_reduction !== null ? o.churn_reduction / 100 : null,
-      acquisition_uplift: o.acquisition_uplift !== null ? o.acquisition_uplift / 100 : null
+      acquisition_uplift: o.acquisition_uplift !== null ? o.acquisition_uplift / 100 : null,
+      gross_margin: o.gross_margin !== null ? o.gross_margin / 100 : null,
+      adoption_ramp_months: o.adoption_ramp_months !== null ? parseInt(o.adoption_ramp_months as any) : null
     }));
 
     return buildDraftScenario(
@@ -846,7 +858,9 @@
     arpu_uplift: { label: 'AI ARPU Uplift ($ Flat)', chip: 'ARPU Uplift $', isPercent: false, symbol: '$' },
     arpu_uplift_percent: { label: 'AI ARPU Uplift (%)', chip: 'ARPU Uplift %', isPercent: true, symbol: '%' },
     churn_reduction: { label: 'AI Churn Reduction', chip: 'Churn Reduction', isPercent: true, symbol: '%' },
-    acquisition_uplift: { label: 'AI Acquisition Uplift', chip: 'Acquisition Uplift', isPercent: true, symbol: '%' }
+    acquisition_uplift: { label: 'AI Acquisition Uplift', chip: 'Acquisition Uplift', isPercent: true, symbol: '%' },
+    gross_margin: { label: 'Gross Margin (%)', chip: 'Gross Margin', isPercent: true, symbol: '%' },
+    adoption_ramp_months: { label: 'Adoption Ramp (months)', chip: 'Ramp Months', isPercent: false, symbol: 'mo' }
   };
 
   function getCohortListForTarget(ov: OverrideRow) {
@@ -1373,6 +1387,14 @@
                               <Label class="text-xs font-semibold">AI Adoption Rate (%)</Label>
                               <Input type="number" step="0.1" min="0" max="100" placeholder="Inherit" bind:value={ov.ai_adoption_rate} class="bg-background text-xs font-mono" />
                             </div>
+                            <div class="space-y-1">
+                              <Label class="text-xs font-semibold">Gross Margin (%)</Label>
+                              <Input type="number" step="0.1" min="0" max="100" placeholder="Inherit" bind:value={ov.gross_margin} class="bg-background text-xs font-mono" />
+                            </div>
+                            <div class="space-y-1">
+                              <Label class="text-xs font-semibold">Adoption Ramp (months)</Label>
+                              <Input type="number" step="1" min="0" max="120" placeholder="Inherit" bind:value={ov.adoption_ramp_months} class="bg-background text-xs font-mono" />
+                            </div>
                           </div>
                         </div>
 

src/lib/shared/financial-math.test.ts

@@ -3592,6 +3592,114 @@ describe('ADR 0012 amendment — two knobs', () => {
       expect(result.compositeBreakdown?.agentMonetization.revenuePv).toBeCloseTo(10000, 0);
     });
   });
+
+  describe('adoption_ramp_months regression — ramp duration MUST affect NPV', () => {
+    // Minimal fixtures for ramp regression testing
+    const rampProvider: Provider = {
+      id: 'rp1', name: 'RampProvider', model_name: 'gpt-4', input_price: 5, output_price: 15,
+      is_predefined: true, currency: 'USD',
+      input_tokens_per_credit: 1000000, output_tokens_per_credit: 333333, updated_at: ''
+    };
+
+    const rampCohort: CohortConfig = {
+      id: 'rc1', name: 'Ramp Cohort',
+      current_users: 5250,
+      monthly_acquisition: 0,
+      acquisition_growth_rate: 0,
+      monthly_churn_rate: 0.02,
+      retention_floor: 0.50,
+      monthly_expansion_rate: 0,
+      ai_adoption_rate: 0.08,
+      base_arpu: 100,
+      arpu_uplift: 349,
+      gross_margin: 0.90,
+      adoption_ramp_months: 3
+    };
+
+    it('cohort carrier: ramp 3 vs ramp 11 produces different NPVs', () => {
+      const baseScenario: Scenario = {
+        id: 'ramp-cohort-sc', name: 'Ramp Cohort Test',
+        projection_months: 12,
+        discount_rate: 0.10,
+        scope_type: 'cohorts',
+        scope_cohorts: [{ ...rampCohort, adoption_ramp_months: 3 }],
+        services: [],
+        costs: []
+      };
+      const resultsRamp3 = calculateScenario(baseScenario, [rampProvider]);
+
+      const scenarioRamp11 = {
+        ...baseScenario,
+        scope_cohorts: [{ ...rampCohort, adoption_ramp_months: 11 }]
+      };
+      const resultsRamp11 = calculateScenario(scenarioRamp11, [rampProvider]);
+
+      // Longer ramp → delayed revenue → lower NPV
+      expect(resultsRamp3.npvUpper).toBeGreaterThan(resultsRamp11.npvUpper);
+      // The difference should be non-trivial (at least 1%)
+      const diffPct = (resultsRamp3.npvUpper - resultsRamp11.npvUpper) / resultsRamp3.npvUpper;
+      expect(diffPct).toBeGreaterThan(0.01);
+    });
+
+    it('composite carrier + addon service: ramp 3 vs ramp 11 produces different NPVs', () => {
+      const addonService: Service & { rollout_month: number; monetization?: MonetizationConfig } = {
+        id: 'ramp-svc1', name: 'AI Insights Addon', status: 'planned',
+        provider_id: 'rp1',
+        avg_input_tokens: 1000, avg_output_tokens: 500,
+        avg_requests_per_user_month: 10,
+        fixed_cost_per_month: 0,
+        service_type: 'agent',
+        rollout_month: 0,
+        monetization: { monetization_type: 'addon', addon_monthly_fee: 50 }
+      };
+
+      const compositeBase: Scenario = {
+        id: 'ramp-comp-sc', name: 'Ramp Composite Test',
+        projection_months: 12,
+        discount_rate: 0.10,
+        scope_type: 'cohorts',
+        modeling_type: 'composite',
+        revenue_carrier: 'composite',
+        arpu_uplift_includes_monetization: false,
+        scope_cohorts: [{ ...rampCohort, arpu_uplift: 0, adoption_ramp_months: 3 }],
+        services: [addonService],
+        costs: []
+      };
+      const resultsRamp3 = calculateScenario(compositeBase, [rampProvider]);
+
+      const compositeRamp11 = {
+        ...compositeBase,
+        scope_cohorts: [{ ...rampCohort, arpu_uplift: 0, adoption_ramp_months: 11 }]
+      };
+      const resultsRamp11 = calculateScenario(compositeRamp11, [rampProvider]);
+
+      // Longer ramp → fewer AI users in early months → lower addon revenue → lower NPV
+      expect(resultsRamp3.npvUpper).toBeGreaterThan(resultsRamp11.npvUpper);
+      const diffPct = (resultsRamp3.npvUpper - resultsRamp11.npvUpper) / resultsRamp3.npvUpper;
+      expect(diffPct).toBeGreaterThan(0.01);
+    });
+
+    it('ramp=0 (instant adoption) should produce the highest NPV', () => {
+      const baseScenario: Scenario = {
+        id: 'ramp-zero-sc', name: 'Ramp Zero Test',
+        projection_months: 12,
+        discount_rate: 0.10,
+        scope_type: 'cohorts',
+        scope_cohorts: [{ ...rampCohort, adoption_ramp_months: 0 }],
+        services: [],
+        costs: []
+      };
+      const resultsNoRamp = calculateScenario(baseScenario, [rampProvider]);
+
+      const scenarioRamp6 = {
+        ...baseScenario,
+        scope_cohorts: [{ ...rampCohort, adoption_ramp_months: 6 }]
+      };
+      const resultsRamp6 = calculateScenario(scenarioRamp6, [rampProvider]);
+
+      expect(resultsNoRamp.npvUpper).toBeGreaterThan(resultsRamp6.npvUpper);
+    });
+  });
 });