@theromans/convex-dobty 0.1.0

package/src/component/schema.ts

@@ -0,0 +1,209 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  /** Static question catalog — seeded at init from static data */
+  questions: defineTable({
+    questionKey: v.string(),
+    domain: v.string(),
+    dimension: v.string(),
+    category: v.string(),
+    itemKey: v.string(),
+    label: v.string(),
+    labelEn: v.optional(v.string()),
+    answerSchema: v.string(),
+    options: v.optional(v.any()),
+    pmNpm: v.optional(v.string()),
+    sortOrder: v.number(),
+  })
+    .index("by_domain", ["domain"])
+    .index("by_domain_dimension", ["domain", "dimension"])
+    .index("by_questionKey", ["questionKey"]),
+
+  /** Per-workspace, per-question answers */
+  answers: defineTable({
+    workspaceId: v.string(),
+    questionKey: v.string(),
+    value: v.any(),
+    source: v.string(),
+    confidence: v.optional(v.number()),
+    extractedFrom: v.optional(v.string()),
+    answeredBy: v.optional(v.string()),
+    verifiedBy: v.optional(v.string()),
+    verifiedAt: v.optional(v.number()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_workspace", ["workspaceId"])
+    .index("by_workspace_question", ["workspaceId", "questionKey"]),
+
+  /** Current computed scores per workspace per domain */
+  metrics: defineTable({
+    workspaceId: v.string(),
+    domain: v.string(),
+    data: v.any(),
+    computedAt: v.number(),
+  })
+    .index("by_workspace", ["workspaceId"])
+    .index("by_workspace_domain", ["workspaceId", "domain"]),
+
+  /** Addon configuration — single record per key */
+  config: defineTable({
+    key: v.string(),
+    enabled: v.boolean(),
+    mode: v.string(),
+    financialInputs: v.optional(v.any()),
+    sensitivity: v.optional(v.any()),
+    lifetime: v.optional(v.any()),
+    workspaceTypes: v.optional(v.any()),
+    snapshotPolicy: v.optional(v.string()),
+    snapshotThreshold: v.optional(v.number()),
+    updatedAt: v.number(),
+  })
+    .index("by_key", ["key"]),
+
+  /** Historical snapshots — immutable after creation */
+  snapshots: defineTable({
+    workspaceId: v.string(),
+    domain: v.string(),
+    dimensionScores: v.any(),
+    overallMaturity: v.any(),
+    monetaryPotential: v.optional(v.any()),
+    financialInputs: v.optional(v.any()),
+    snapshotAt: v.number(),
+    snapshotType: v.string(),
+  })
+    .index("by_workspace", ["workspaceId"])
+    .index("by_workspace_domain", ["workspaceId", "domain"]),
+
+  // ── 5DoBT Potential Analysis Tables ──
+
+  /** Top-level analysis record */
+  potentialAnalyses: defineTable({
+    workspaceId: v.string(),
+    name: v.optional(v.string()),
+    currentStep: v.number(),
+    status: v.string(),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_workspace", ["workspaceId"]),
+
+  /** Step I: Project Charter */
+  paProjectCharters: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    name: v.string(),
+    date: v.string(),
+    business_case: v.string(),
+    problem_statement: v.string(),
+    goal: v.string(),
+    scope_in: v.string(),
+    scope_out: v.string(),
+    objectives: v.any(),
+    conditions: v.optional(v.string()),
+    risks: v.optional(v.any()),
+    costs: v.optional(v.string()),
+    milestones: v.optional(v.any()),
+    project_team: v.optional(v.any()),
+  })
+    .index("by_analysis", ["analysisId"]),
+
+  /** Step II: Definition of Done items */
+  paDefinitionsOfDone: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    number: v.number(),
+    definition: v.string(),
+    description: v.string(),
+    effect_type: v.string(),
+  })
+    .index("by_analysis", ["analysisId"]),
+
+  /** Step III: Influence Area selections */
+  paInfluenceAreas: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    dobt_dimension: v.string(),
+    sub_area_key: v.string(),
+    potential_description: v.string(),
+  })
+    .index("by_analysis", ["analysisId"])
+    .index("by_analysis_dimension", ["analysisId", "dobt_dimension"]),
+
+  /** Step IV: Points of Changes */
+  paPointsOfChanges: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    influence_area_ref: v.id("paInfluenceAreas"),
+    poc_description: v.string(),
+    definition_of_done_refs: v.any(),
+  })
+    .index("by_analysis", ["analysisId"]),
+
+  /** Step V: Fields of Action */
+  paFieldsOfAction: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    poc_ref: v.id("paPointsOfChanges"),
+    potential_description: v.string(),
+    dobt_dimension: v.string(),
+    influence_type: v.string(),
+    foa_description: v.string(),
+    kpi_influence: v.string(),
+  })
+    .index("by_analysis", ["analysisId"])
+    .index("by_analysis_dimension", ["analysisId", "dobt_dimension"]),
+
+  /** Step VI: Potential Status per FOA */
+  paPotentialStatuses: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    foa_ref: v.id("paFieldsOfAction"),
+    status: v.string(),
+    validation_level: v.optional(v.string()),
+    estimation_value: v.optional(v.number()),
+    estimation_risk: v.optional(v.number()),
+    estimation_explanation: v.optional(v.string()),
+    estimation_result: v.optional(v.number()),
+    calculation_ref: v.optional(v.id("paCalculations")),
+    calculation_result: v.optional(v.number()),
+    committed_value_result: v.optional(v.number()),
+    committed_responsible_business_owner: v.optional(v.string()),
+    measured_potential_value: v.optional(v.number()),
+  })
+    .index("by_analysis", ["analysisId"])
+    .index("by_foa", ["foa_ref"]),
+
+  /** Step VII: Facts & Figures */
+  paFactsFigures: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    name: v.string(),
+    unit: v.string(),
+    value: v.number(),
+  })
+    .index("by_analysis", ["analysisId"]),
+
+  /** Step VII: Calculations per dimension */
+  paCalculations: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    dobt_dimension: v.string(),
+    potential_description: v.string(),
+    assumptions: v.any(),
+    formula: v.string(),
+    result: v.number(),
+  })
+    .index("by_analysis", ["analysisId"]),
+
+  /** Step VII: Computed Calculation Summary (cached) */
+  paCalculationSummaries: defineTable({
+    analysisId: v.id("potentialAnalyses"),
+    dimension_totals: v.any(),
+    grand_total_sp: v.number(),
+    grand_total_nsp: v.number(),
+    grand_total: v.number(),
+    sensitivity: v.any(),
+    margin_effects: v.any(),
+    total_margin_effect: v.number(),
+    lifetime: v.any(),
+    projection: v.any(),
+    validated_potentials: v.any(),
+    calculatedAt: v.number(),
+  })
+    .index("by_analysis", ["analysisId"]),
+});

package/src/component/scoring.ts

@@ -0,0 +1,485 @@
+import { internalMutation } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { v } from "convex/values";
+import { DOMAINS, getDomain, getMaturityLevel } from "../data/domains.js";
+import { KM_METHODS } from "../data/km/methods.js";
+import { KM_SYSTEMS } from "../data/km/systems.js";
+import { KM_GUIDELINES } from "../data/km/guidelines.js";
+import { KM_CVR_WEIGHTS, KM_CVR_BUILDUP, KM_IMPLEMENTATION_FACTORS } from "../data/km/cvr.js";
+import { EK_METHODS } from "../data/ek/methods.js";
+import { EK_SYSTEMS } from "../data/ek/systems.js";
+import { EK_GUIDELINES } from "../data/ek/guidelines.js";
+import { EK_CVR_WEIGHTS, EK_CVR_BUILDUP, EK_IMPLEMENTATION_FACTORS } from "../data/ek/cvr.js";
+import { DM_METHODS } from "../data/dm/methods.js";
+import { DM_SYSTEMS } from "../data/dm/systems.js";
+import { DM_GUIDELINES } from "../data/dm/guidelines.js";
+import { DM_CVR_WEIGHTS, DM_CVR_BUILDUP, DM_IMPLEMENTATION_FACTORS } from "../data/dm/cvr.js";
+import {
+  VALUE_CATEGORIES,
+  DEFAULT_SENSITIVITY,
+  DEFAULT_LIFETIME,
+} from "../data/types.js";
+import type {
+  ItemDef,
+  DomainKey,
+  CvrWeightTable,
+  CvrBuildupTable,
+  ImplementationFactorTable,
+  ValueCategory,
+  FinancialInputs,
+  SensitivityConfig,
+  LifetimeConfig,
+  Sub5Value,
+  CvrWeightRow,
+} from "../data/types.js";
+
+// ── Static Data Lookup ──
+
+function getItemsForDomain(domain: DomainKey): {
+  methods: ItemDef[];
+  systems: ItemDef[];
+  guidelines: ItemDef[];
+} {
+  switch (domain) {
+    case "KM":
+      return { methods: KM_METHODS, systems: KM_SYSTEMS, guidelines: KM_GUIDELINES };
+    case "EK":
+      return { methods: EK_METHODS, systems: EK_SYSTEMS, guidelines: EK_GUIDELINES };
+    case "DM":
+      return { methods: DM_METHODS, systems: DM_SYSTEMS, guidelines: DM_GUIDELINES };
+  }
+}
+
+function getCvrData(domain: DomainKey): {
+  weights: CvrWeightTable;
+  buildup: CvrBuildupTable;
+  factors: ImplementationFactorTable;
+} {
+  switch (domain) {
+    case "KM":
+      return { weights: KM_CVR_WEIGHTS, buildup: KM_CVR_BUILDUP, factors: KM_IMPLEMENTATION_FACTORS };
+    case "EK":
+      return { weights: EK_CVR_WEIGHTS, buildup: EK_CVR_BUILDUP, factors: EK_IMPLEMENTATION_FACTORS };
+    case "DM":
+      return { weights: DM_CVR_WEIGHTS, buildup: DM_CVR_BUILDUP, factors: DM_IMPLEMENTATION_FACTORS };
+  }
+}
+
+// ── Scoring Helpers ──
+
+/**
+ * Derive an anchoring level (0-3) from sub5 answer.
+ * 0 = not known/used, 1 = basic, 2 = intermediate, 3 = fully anchored
+ */
+function sub5ToLevel(val: Sub5Value | null): number {
+  if (!val) return 0;
+  if (!val.bekannt) return 0;
+  if (!val.in_anwendung) return 0;
+  let level = 1; // known + in use
+  if (val.definiert) level = 2;
+  if (val.verankert && val.verankert !== null) {
+    // System-anchored is highest
+    if (val.verankert === "system_anchored") level = 3;
+    else if (val.verankert === "process_anchored") level = Math.max(level, 2);
+  }
+  if (val.schulungen && level >= 2) level = 3;
+  return level;
+}
+
+/**
+ * Compute item score using the level-based formula.
+ * Returns { score: 0-4, maxPotential, methodShare }
+ */
+function computeItemScore(
+  item: ItemDef,
+  level: number,
+  complexity: number,
+): { score: number; maxPotential: number } {
+  const [w1, w2, w3] = item.weights;
+  const complexityIdx = complexity - 1; // 0-3
+  const complexityInfluence = item.complexityRelevance[complexityIdx] ?? 1;
+  const maxPotential = (w1 + w2 + w3) * complexityInfluence;
+
+  if (maxPotential === 0) {
+    return { score: 4, maxPotential: 0 }; // not relevant for this complexity
+  }
+
+  let score: number;
+  if (level === 0) {
+    score = 0;
+  } else if (level === 1) {
+    score = (w1 * complexityInfluence) / maxPotential * 4;
+  } else if (level === 2) {
+    score = ((w1 + w2) * complexityInfluence) / maxPotential * 4;
+  } else {
+    score = 4; // level 3 = full potential
+  }
+
+  return { score, maxPotential };
+}
+
+/**
+ * Aggregate item scores using SUMPRODUCT: SUM(score * share)
+ * where share = maxPotential / SUM(allMaxPotentials)
+ */
+function aggregateSumproduct(
+  items: Array<{ score: number; maxPotential: number }>,
+): number {
+  const totalPotential = items.reduce((sum, i) => sum + i.maxPotential, 0);
+  if (totalPotential === 0) return 0;
+  return items.reduce(
+    (sum, i) => sum + i.score * (i.maxPotential / totalPotential),
+    0,
+  );
+}
+
+/**
+ * Aggregate item scores using AVERAGE
+ */
+function aggregateAverage(scores: number[]): number {
+  if (scores.length === 0) return 0;
+  return scores.reduce((sum, s) => sum + s, 0) / scores.length;
+}
+
+// ── Main Recompute ──
+
+/** Full recompute: answers → item scores → dimension scores → overall → CVR → metrics table */
+export const recomputeMetrics = internalMutation({
+  args: {
+    workspaceId: v.string(),
+    domain: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const domain = args.domain as DomainKey;
+    const domainDef = getDomain(domain);
+    if (!domainDef) return;
+
+    // Load config for financial inputs and complexity
+    const config = await ctx.db
+      .query("config")
+      .withIndex("by_key", (q) => q.eq("key", "dobt-addon"))
+      .first();
+
+    const financialInputs = (config?.financialInputs as FinancialInputs) ?? {
+      revenue: 0,
+      cost_volume: 0,
+      manufacturing_costs: 0,
+      complexity: 3 as const,
+    };
+    const sensitivity = (config?.sensitivity as SensitivityConfig) ?? DEFAULT_SENSITIVITY;
+    const lifetime = (config?.lifetime as LifetimeConfig) ?? DEFAULT_LIFETIME;
+    const complexity = financialInputs.complexity || 3;
+
+    // Load answers for this workspace
+    const answers = await ctx.db
+      .query("answers")
+      .withIndex("by_workspace", (q) => q.eq("workspaceId", args.workspaceId))
+      .collect();
+    const answerMap = new Map(answers.map((a) => [a.questionKey, a]));
+
+    // Get items
+    const { methods, systems, guidelines } = getItemsForDomain(domain);
+
+    // Compute dimension scores
+    const dimensionScores: Record<string, { status: number; target: number; gap: number }> = {};
+
+    for (const dim of domainDef.dimensions) {
+      let score: number;
+
+      if (dim.scoringSource === "expert") {
+        // Direct expert score
+        const qKey = `${domain.toLowerCase()}_expert_${dim.key}`;
+        const answer = answerMap.get(qKey);
+        score = answer ? Number(answer.value) || 0 : 0;
+
+        // Handle PM/NPM split for EK expert dimensions
+        if (dim.pmNpmSplit) {
+          const pmKey = `${domain.toLowerCase()}_expert_${dim.key}_pm`;
+          const npmKey = `${domain.toLowerCase()}_expert_${dim.key}_npm`;
+          const pmAnswer = answerMap.get(pmKey);
+          const npmAnswer = answerMap.get(npmKey);
+          if (pmAnswer || npmAnswer) {
+            const pmScore = pmAnswer ? Number(pmAnswer.value) || 0 : 0;
+            const npmScore = npmAnswer ? Number(npmAnswer.value) || 0 : 0;
+            score = (pmScore + npmScore) / 2;
+          }
+        }
+      } else {
+        // Methods/systems/guidelines scoring
+        let items: ItemDef[];
+        if (dim.scoringSource === "methods") {
+          items = methods.filter((m) => m.dimension === dim.key);
+        } else if (dim.scoringSource === "systems") {
+          items = systems.filter((s) => s.dimension === dim.key);
+          // Include methods assigned to this dimension (e.g., DM technologies in dm_systeme)
+          items.push(...methods.filter((m) => m.dimension === dim.key));
+        } else {
+          items = guidelines.filter((g) => g.dimension === dim.key);
+        }
+
+        if (dim.pmNpmSplit && domain === "EK") {
+          // EK PM/NPM split: compute separately then average
+          // "both" items participate in both PM and NPM groups
+          const pmItems = items.filter((i) => i.pmNpm === "pm" || i.pmNpm === "both");
+          const npmItems = items.filter((i) => i.pmNpm === "npm" || i.pmNpm === "both");
+
+          const computeGroupScore = (groupItems: ItemDef[]): number => {
+            const scored = groupItems.map((item) => {
+              const qKey = `${domain.toLowerCase()}_${item.category}_${item.key}`;
+              const answer = answerMap.get(qKey);
+              const level = answer ? sub5ToLevel(answer.value as Sub5Value) : 0;
+              return computeItemScore(item, level, complexity);
+            });
+            return aggregateSumproduct(scored);
+          };
+
+          const pmScore = pmItems.length > 0 ? computeGroupScore(pmItems) : 0;
+          const npmScore = npmItems.length > 0 ? computeGroupScore(npmItems) : 0;
+          score = (pmScore + npmScore) / 2;
+        } else {
+          // Standard scoring
+          const scored = items.map((item) => {
+            const qKey = `${domain.toLowerCase()}_${item.category}_${item.key}`;
+            const answer = answerMap.get(qKey);
+            const level = answer ? sub5ToLevel(answer.value as Sub5Value) : 0;
+            return computeItemScore(item, level, complexity);
+          });
+
+          if (dim.aggregationMethod === "average") {
+            score = aggregateAverage(scored.map((s) => s.score));
+          } else {
+            score = aggregateSumproduct(scored);
+          }
+        }
+      }
+
+      dimensionScores[dim.key] = {
+        status: Math.round(score * 100) / 100,
+        target: 4, // target is always World Class
+        gap: Math.round((4 - score) * 100) / 100,
+      };
+    }
+
+    // Overall maturity
+    const dimSum = Object.values(dimensionScores).reduce((sum, d) => sum + d.status, 0);
+    const overallScore = (dimSum / domainDef.maxScore) * 4;
+    const overallMaturity = {
+      overall_score: Math.round(overallScore * 100) / 100,
+      maturity_level: getMaturityLevel(overallScore),
+    };
+
+    // CVR monetization
+    const { weights: cvrWeights, buildup: cvrBuildup, factors: implFactors } = getCvrData(domain);
+    const monetaryBasis = computeMonetaryBasis(domain, financialInputs);
+    const monetaryPotential = computeCvrMonetization(
+      domain,
+      dimensionScores,
+      cvrWeights,
+      cvrBuildup,
+      implFactors,
+      monetaryBasis,
+      sensitivity,
+      lifetime,
+    );
+
+    // Progress stats
+    const domainPrefix = domain.toLowerCase() + "_";
+    const domainAnswers = answers.filter((a) => a.questionKey.startsWith(domainPrefix));
+    const allQuestions = await ctx.db
+      .query("questions")
+      .withIndex("by_domain", (q) => q.eq("domain", domain))
+      .collect();
+    const progress = {
+      total: allQuestions.length,
+      answered: domainAnswers.length,
+      progressPct: allQuestions.length > 0 ? Math.round((domainAnswers.length / allQuestions.length) * 100) : 0,
+    };
+
+    // Store metrics
+    const data = {
+      dimensionScores,
+      overallMaturity,
+      monetaryPotential,
+      progress,
+    };
+
+    const existing = await ctx.db
+      .query("metrics")
+      .withIndex("by_workspace_domain", (q) =>
+        q.eq("workspaceId", args.workspaceId).eq("domain", domain),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, { data, computedAt: Date.now() });
+    } else {
+      await ctx.db.insert("metrics", {
+        workspaceId: args.workspaceId,
+        domain,
+        data,
+        computedAt: Date.now(),
+      });
+    }
+
+    // Snapshot policy check
+    const snapshotPolicy = (config?.snapshotPolicy as string) ?? "auto";
+    let shouldSnapshot = false;
+
+    if (snapshotPolicy === "auto") {
+      shouldSnapshot = true;
+    } else if (snapshotPolicy === "threshold" && existing) {
+      // Only snapshot when score changes by more than threshold %
+      const threshold = (config?.snapshotThreshold as number) ?? 5;
+      const oldData = existing.data as Record<string, unknown>;
+      const oldMaturity = oldData.overallMaturity as { overall_score: number } | undefined;
+      const oldScore = oldMaturity?.overall_score ?? 0;
+      const newScore = overallMaturity.overall_score;
+      const changePct = oldScore > 0 ? Math.abs(newScore - oldScore) / oldScore * 100 : 100;
+      shouldSnapshot = changePct >= threshold;
+    }
+    // "manual" and "periodic" don't auto-snapshot from recompute
+
+    if (shouldSnapshot) {
+      await ctx.scheduler.runAfter(0, internal.metrics.createSnapshot, {
+        workspaceId: args.workspaceId,
+        domain,
+        snapshotType: snapshotPolicy === "auto" ? "auto" : "threshold",
+      });
+    }
+  },
+});
+
+// ── CVR Helpers ──
+
+function computeMonetaryBasis(
+  domain: DomainKey,
+  fi: FinancialInputs,
+): Record<ValueCategory, number> {
+  if (domain === "EK") {
+    // EK uses material-based factors
+    const directMat = fi.direct_material ?? 0;
+    const indirectMat = fi.indirect_material ?? 0;
+    return {
+      overhead: (fi.headcount_ek ?? 0) * 80000,
+      direct_cost: directMat * 0.01,
+      additional_business: (directMat + indirectMat) * 0.02,
+      innovation: (directMat + indirectMat) * 0.02,
+      risk: (directMat + indirectMat) * 0.0025,
+    };
+  }
+  // KM and DM use standard factors
+  const headcount = domain === "KM" ? (fi.headcount_km ?? 0) : 0;
+  return {
+    overhead: headcount * 80000,
+    direct_cost: fi.manufacturing_costs * 0.01,
+    additional_business: fi.revenue * 0.02,
+    innovation: fi.revenue * 0.02,
+    risk: fi.cost_volume * 0.0025,
+  };
+}
+
+function computeCvrMonetization(
+  domain: DomainKey,
+  dimensionScores: Record<string, { status: number; target: number; gap: number }>,
+  cvrWeights: CvrWeightTable,
+  cvrBuildup: CvrBuildupTable,
+  implFactors: ImplementationFactorTable,
+  monetaryBasis: Record<ValueCategory, number>,
+  sensitivity: SensitivityConfig,
+  lifetime: LifetimeConfig,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const totals = {
+    total_utilized_monetary: 0,
+    total_unused_monetary: 0,
+    total_secured_margin: 0,
+    total_margin_effect: 0,
+    lifetime: { year_1: 0, year_2: 0, year_3: 0, total_3yr: 0 },
+  };
+
+  // For EK, compute CVR separately with PM and NPM factors, then average.
+  // For KM/DM, use the single domain factor key.
+  const factorKeys = domain === "EK" ? ["EK_PM", "EK_NPM"] : [domain];
+
+  for (const vc of VALUE_CATEGORIES) {
+    // Sum CVR across all dimensions for this value category
+    let totalCvrMax = 0;
+    let utilized = 0;
+    let improvementDelta = 0;
+
+    for (const [dimKey, dimData] of Object.entries(dimensionScores)) {
+      const cvrMax = cvrWeights[dimKey]?.[vc] ?? 0;
+      totalCvrMax += cvrMax;
+
+      // Utilization: score * cvr_max
+      utilized += dimData.status * cvrMax;
+
+      // Improvement: (target - status) * cvr_max
+      improvementDelta += dimData.gap * cvrMax;
+    }
+
+    const maxUtilized = totalCvrMax * 4;
+    const utilizationRatio = maxUtilized > 0 ? utilized / maxUtilized : 0;
+    const basis = monetaryBasis[vc];
+    const utilizedMonetary = utilizationRatio * basis;
+    const unusedMonetary = (1 - utilizationRatio) * basis;
+
+    const improvementRate = maxUtilized > 0 ? improvementDelta / maxUtilized : 0;
+    const monetaryImprovement = improvementRate * basis;
+
+    // Average implementation factor across PM/NPM (or single factor for KM/DM)
+    const implFactor = factorKeys.reduce(
+      (sum, fk) => sum + (implFactors[fk]?.[vc] ?? 0),
+      0,
+    ) / factorKeys.length;
+    const securedMargin = implFactor * monetaryImprovement;
+
+    // Sensitivity analytics
+    const marginConversion = getMarginConversionFactor(vc, sensitivity);
+    const marginEffect = securedMargin * marginConversion;
+
+    // Lifetime projection
+    const ltYear1 = marginEffect * lifetime.year_1;
+    const ltYear2 = marginEffect * lifetime.year_2;
+    const ltYear3 = marginEffect * lifetime.year_3;
+
+    result[vc] = {
+      monetary_basis: Math.round(basis),
+      utilization_ratio: Math.round(utilizationRatio * 10000) / 10000,
+      utilized_monetary: Math.round(utilizedMonetary),
+      unused_monetary: Math.round(unusedMonetary),
+      improvement_rate: Math.round(improvementRate * 10000) / 10000,
+      monetary_improvement: Math.round(monetaryImprovement),
+      secured_margin: Math.round(securedMargin),
+      margin_effect: Math.round(marginEffect),
+      lifetime: {
+        year_1: Math.round(ltYear1),
+        year_2: Math.round(ltYear2),
+        year_3: Math.round(ltYear3),
+        total_3yr: Math.round(ltYear1 + ltYear2 + ltYear3),
+      },
+    };
+
+    totals.total_utilized_monetary += Math.round(utilizedMonetary);
+    totals.total_unused_monetary += Math.round(unusedMonetary);
+    totals.total_secured_margin += Math.round(securedMargin);
+    totals.total_margin_effect += Math.round(marginEffect);
+    totals.lifetime.year_1 += Math.round(ltYear1);
+    totals.lifetime.year_2 += Math.round(ltYear2);
+    totals.lifetime.year_3 += Math.round(ltYear3);
+    totals.lifetime.total_3yr += Math.round(ltYear1 + ltYear2 + ltYear3);
+  }
+
+  result.totals = totals;
+  return result;
+}
+
+function getMarginConversionFactor(vc: ValueCategory, s: SensitivityConfig): number {
+  switch (vc) {
+    case "overhead": return s.efficiency_to_margin;
+    case "direct_cost": return s.direct_cost_to_margin;
+    case "additional_business": return s.revenue_to_margin;
+    case "innovation": return s.innovation_to_margin;
+    case "risk": return s.risk_to_margin;
+  }
+}