2sagaco48 1.0.0

package/src/lib/quant-engine.ts

@@ -0,0 +1,231 @@
+// MODULE A — VC / Medallion-grade Quantitative Engine.
+// Deterministic, pure-TypeScript, composable, side-effect free.
+
+// ─── Unit economics ─────────────────────────────────────────────────
+export const mrr = (customers: number, arpu: number) => customers * arpu;
+export const arr = (m: number) => m * 12;
+export const cac = (sm: number, n: number) => n > 0 ? sm / n : NaN;
+export const ltv = (arpuM: number, gm: number, churnM: number) => churnM > 0 ? (arpuM * gm) / churnM : NaN;
+export const ltvCacRatio = (l: number, c: number) => c > 0 ? l / c : NaN;
+export const cacPaybackMonths = (c: number, arpuM: number, gm: number) => c / (arpuM * gm);
+export const nrr = (start: number, exp: number, contr: number, churn: number) => start > 0 ? (start + exp - contr - churn) / start : NaN;
+export const grr = (start: number, contr: number, churn: number) => start > 0 ? (start - contr - churn) / start : NaN;
+export const magicNumber = (netNewARR: number, priorQSM: number) => priorQSM > 0 ? netNewARR / priorQSM : NaN;
+export const burnMultiple = (netBurn: number, netNewARR: number) => netNewARR > 0 ? netBurn / netNewARR : NaN;
+export const ruleOf40 = (growthPct: number, marginPct: number) => growthPct + marginPct;
+export const monthsRunway = (cash: number, monthlyBurn: number) => monthlyBurn > 0 ? cash / monthlyBurn : Infinity;
+
+// ─── DCF / IRR / WACC / CAPM ────────────────────────────────────────
+export interface DcfResult {
+  pvCashFlows: number; pvTerminal: number; enterpriseValue: number;
+  terminalPctOfEV: number; impliedExitMultiple: number;
+}
+export function dcfNpv(cashFlows: number[], discountRate: number, terminalGrowth = 0.02): DcfResult {
+  const n = cashFlows.length;
+  const tv = cashFlows[n - 1] * (1 + terminalGrowth) / (discountRate - terminalGrowth);
+  const pvCfs = cashFlows.reduce((acc, cf, t) => acc + cf / Math.pow(1 + discountRate, t + 1), 0);
+  const pvTerm = tv / Math.pow(1 + discountRate, n);
+  const ev = pvCfs + pvTerm;
+  return { pvCashFlows: pvCfs, pvTerminal: pvTerm, enterpriseValue: ev,
+    terminalPctOfEV: pvTerm / ev, impliedExitMultiple: tv / cashFlows[n - 1] };
+}
+export function irr(cashFlows: number[], guess = 0.1): number {
+  let rate = guess;
+  for (let i = 0; i < 1000; i++) {
+    const npv = cashFlows.reduce((a, cf, t) => a + cf / Math.pow(1 + rate, t), 0);
+    const dnpv = cashFlows.reduce((a, cf, t) => a + (-t * cf) / Math.pow(1 + rate, t + 1), 0);
+    if (Math.abs(dnpv) < 1e-12) break;
+    rate -= npv / dnpv;
+  }
+  return rate;
+}
+export const moic = (exit: number, invested: number) => invested > 0 ? exit / invested : NaN;
+export const wacc = (eq: number, costEq: number, dbt: number, costDbt: number, tax: number) =>
+  eq * costEq + dbt * costDbt * (1 - tax);
+export const capm = (rf: number, beta: number, mp: number, size = 0, country = 0) =>
+  rf + beta * mp + size + country;
+
+// ─── VC method ──────────────────────────────────────────────────────
+export function vcMethodPreMoney(exitValue: number, targetIRR: number, years: number, dilution = 0.2): number {
+  const pv = exitValue / Math.pow(1 + targetIRR, years);
+  return pv * (1 - dilution);
+}
+
+// ─── Portfolio / fund / signal stats ───────────────────────────────
+export interface WaterfallResult {
+  grossMOIC: number; netMOIC: number; grossIRRApprox: number;
+  totalMgmtFees: number; gpCarry: number; lpDistributions: number; dpi: number;
+}
+export function fundWaterfall(committed: number, invested: number, totalDistributed: number,
+  mgmtFeePct = 0.02, carryPct = 0.2, preferredReturn = 0.08, fundLife = 10): WaterfallResult {
+  const totalMgmtFees = committed * mgmtFeePct * fundLife;
+  const netInvested = invested - totalMgmtFees;
+  const hurdle = netInvested * (Math.pow(1 + preferredReturn, fundLife) - 1);
+  const profit = Math.max(0, totalDistributed - netInvested);
+  const gpCarry = Math.max(0, (profit - hurdle) * carryPct);
+  const lpNet = totalDistributed - gpCarry;
+  return {
+    grossMOIC: totalDistributed / invested,
+    netMOIC: lpNet / committed,
+    grossIRRApprox: Math.pow(totalDistributed / invested, 1 / fundLife) - 1,
+    totalMgmtFees, gpCarry, lpDistributions: lpNet, dpi: lpNet / committed,
+  };
+}
+export function powerLawPortfolio(n: number, winnerPct = 0.1, winnerMultiple = 20, loserReturn = -1) {
+  const nW = Math.max(1, Math.round(n * winnerPct));
+  const nL = n - nW;
+  const total = nW * winnerMultiple + nL * loserReturn;
+  return { nCompanies: n, nWinners: nW, nLosers: nL,
+    totalPortfolioMOIC: total / n,
+    winnerContributionPct: total !== 0 ? (nW * winnerMultiple) / total : 0,
+    lossRatio: nL / n };
+}
+export function hhi(shares: number[]) {
+  const v = shares.reduce((a, s) => a + s * s, 0) * 10000;
+  return { hhi: v, classification: v > 2500 ? "Highly Concentrated" : v > 1500 ? "Moderately Concentrated" : "Competitive" };
+}
+
+// ─── Statistical / signal processing ───────────────────────────────
+const mean = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / xs.length;
+const std = (xs: number[], ddof = 1) => {
+  const m = mean(xs);
+  const v = xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - ddof);
+  return Math.sqrt(v);
+};
+
+export const zScore = (value: number, m: number, s: number) => (value - m) / s;
+export const sharpeRatio = (returns: number[], rf = 0) => {
+  const ex = returns.map(r => r - rf);
+  return mean(ex) / std(ex);
+};
+export function sortinoRatio(returns: number[], rf = 0, target = 0) {
+  const ex = returns.map(r => r - rf);
+  const dn = returns.map(r => Math.min(0, r - target) ** 2);
+  const dd = Math.sqrt(mean(dn));
+  return dd > 0 ? mean(ex) / dd : Infinity;
+}
+export function maxDrawdown(equity: number[]): number {
+  let peak = equity[0], maxDD = 0;
+  for (const v of equity) { peak = Math.max(peak, v); maxDD = Math.max(maxDD, (peak - v) / peak); }
+  return maxDD;
+}
+export function kellyCriterion(winProb: number, winLossRatio: number): number {
+  const q = 1 - winProb;
+  return (winProb * winLossRatio - q) / winLossRatio;
+}
+export const informationRatio = (active: number[]) => mean(active) / std(active);
+
+/**
+ * ICC-adjusted Sample Size (Design Effect)
+ * neffective = n / (1 + (m - 1) * rho)
+ * m: cluster size, rho: intraclass correlation
+ */
+export const calcEffectiveN = (n: number, m: number, rho: number) => {
+  const deff = 1 + (m - 1) * rho;
+  return n / deff;
+};
+
+/**
+ * Required nominal N to reach target power given cluster design.
+ * nNominal = nTarget * (1 + (m - 1) * rho)
+ */
+export const calcRequiredNominalN = (nTarget: number, m: number, rho: number) => {
+  return nTarget * (1 + (m - 1) * rho);
+};
+
+// ─── Inverse normal CDF (Acklam's algorithm) — needed for power calcs ───
+function invNorm(p: number): number {
+  if (p <= 0) return -Infinity;
+  if (p >= 1) return Infinity;
+  const a = [-3.969683028665376e+01, 2.209460984245205e+02, -2.759285104469687e+02, 1.383577518672690e+02, -3.066479806614716e+01, 2.506628277459239e+00];
+  const b = [-5.447609879822406e+01, 1.615858368580409e+02, -1.556989798598866e+02, 6.680131188771972e+01, -1.328068155288572e+01];
+  const c = [-7.784894002430293e-03, -3.223964580411365e-01, -2.400758277161838e+00, -2.549732539343734e+00, 4.374664141464968e+00, 2.938163982698783e+00];
+  const d = [7.784695709041462e-03, 3.224671290700398e-01, 2.445134137142996e+00, 3.754408661907416e+00];
+  const plow = 0.02425, phigh = 1 - plow;
+  let q, r;
+  if (p < plow) { q = Math.sqrt(-2 * Math.log(p)); return (((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) / ((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1); }
+  if (p <= phigh) { q = p - 0.5; r = q*q; return (((((a[0]*r+a[1])*r+a[2])*r+a[3])*r+a[4])*r+a[5])*q / (((((b[0]*r+b[1])*r+b[2])*r+b[3])*r+b[4])*r+1); }
+  q = Math.sqrt(-2 * Math.log(1 - p)); return -(((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) / ((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1);
+}
+
+/**
+ * cRCT power calculation: required clusters PER ARM to detect a mean
+ * difference with given power, accounting for ICC design effect AND attrition.
+ *
+ * Two-arm parallel cluster-randomized trial, continuous outcome.
+ *  delta: target mean difference
+ *  sd: pooled standard deviation
+ *  alpha: two-sided significance (default 0.05)
+ *  power: target power (default 0.80)
+ *  icc: intraclass correlation
+ *  clusterSize: AVERAGE evaluable participants per cluster at endpoint
+ *  attrition: fraction lost to follow-up (default 0)
+ */
+export function calcClusterRCTPower(opts: {
+  delta: number; sd: number; alpha?: number; power?: number;
+  icc: number; clusterSize: number; attrition?: number;
+}): {
+  individualsPerArm: number;
+  designEffect: number;
+  evaluablePerArm: number;
+  clustersPerArmIdeal: number;
+  recruitPerCluster: number;
+  clustersPerArmWithAttrition: number;
+  totalClustersWithAttrition: number;
+  totalRecruit: number;
+} {
+  const alpha = opts.alpha ?? 0.05;
+  const power = opts.power ?? 0.80;
+  const attrition = Math.max(0, Math.min(0.95, opts.attrition ?? 0));
+  const m = Math.max(1, opts.clusterSize);
+  const zAlpha = invNorm(1 - alpha / 2);
+  const zBeta = invNorm(power);
+  const effectSize = Math.abs(opts.delta) / opts.sd;
+  // Individual-level N per arm for a two-sample test
+  const nIndiv = Math.ceil((2 * Math.pow(zAlpha + zBeta, 2)) / Math.pow(effectSize, 2));
+  // Design effect inflation
+  const deff = 1 + (m - 1) * opts.icc;
+  const evaluablePerArm = Math.ceil(nIndiv * deff);
+  // Ideal clusters per arm (no attrition)
+  const clustersIdeal = Math.ceil(evaluablePerArm / m);
+  // Attrition adjustment: recruit more per cluster so evaluable = target
+  const recruitPerCluster = attrition > 0 ? Math.ceil(m / (1 - attrition)) : m;
+  const clustersWithAttrition = Math.ceil(evaluablePerArm / m);
+  const totalRecruit = clustersWithAttrition * recruitPerCluster * 2;
+  return {
+    individualsPerArm: nIndiv,
+    designEffect: Math.round(deff * 1000) / 1000,
+    evaluablePerArm,
+    clustersPerArmIdeal: clustersIdeal,
+    recruitPerCluster,
+    clustersPerArmWithAttrition: clustersWithAttrition,
+    totalClustersWithAttrition: clustersWithAttrition * 2,
+    totalRecruit,
+  };
+}
+
+/**
+ * Attrition adequacy check: given a recruitment plan, does it survive attrition?
+ * Returns the post-attrition evaluable count and whether it clears the threshold.
+ */
+export function calcAttritionAdequacy(opts: {
+  clustersPerArm: number; recruitPerCluster: number; attrition: number; requiredEvaluablePerArm: number;
+}): { recruitedPerArm: number; evaluablePerArm: number; adequate: boolean; deficit: number } {
+  const recruited = opts.clustersPerArm * opts.recruitPerCluster;
+  const evaluable = Math.floor(recruited * (1 - opts.attrition));
+  const deficit = opts.requiredEvaluablePerArm - evaluable;
+  return { recruitedPerArm: recruited, evaluablePerArm: evaluable, adequate: deficit <= 0, deficit: Math.max(0, deficit) };
+}
+
+// ─── Display helper ─────────────────────────────────────────────────
+export interface QuantResult { label: string; value: number; unit?: string; formula: string; }
+
+export function fmtPct(x: number): string { return `${(x * 100).toFixed(1)}%`; }
+export function fmtMoney(x: number): string {
+  if (!isFinite(x)) return "—";
+  const abs = Math.abs(x);
+  if (abs >= 1e9) return `$${(x / 1e9).toFixed(2)}B`;
+  if (abs >= 1e6) return `$${(x / 1e6).toFixed(2)}M`;
+  if (abs >= 1e3) return `$${(x / 1e3).toFixed(1)}K`;
+  return `$${x.toFixed(0)}`;
+}

package/src/lib/quant-lib.ts

@@ -0,0 +1,80 @@
+// MODULE A.2 — VC / Medallion-grade Quantitative Engine
+// All formulas below are deterministic functions, taking inputs and returning outputs.
+// These are wired into the ReportOS v3 system for high-rigor financial reporting.
+
+import { QuantResult } from "./reportos";
+
+// ── 8.1.1 Unit Economics ──────────────────────────────────────────────
+
+export function calcCAC(smSpend: number, newCustomers: number): QuantResult {
+  const val = newCustomers > 0 ? smSpend / newCustomers : 0;
+  return { label: "CAC", value: val, unit: "$", formula: "S&M spend / new customers", inputs: { smSpend, newCustomers } };
+}
+
+export function calcLTV(arpuMonthly: number, grossMarginPct: number, churnMonthly: number): QuantResult {
+  const val = churnMonthly > 0 ? (arpuMonthly * grossMarginPct) / churnMonthly : 0;
+  return { label: "LTV", value: val, unit: "$", formula: "(ARPU × GM%) / churn", inputs: { arpuMonthly, grossMarginPct, churnMonthly } };
+}
+
+export function calcNRR(beginningRev: number, expansionRev: number, contractionRev: number, churnRev: number): QuantResult {
+  const val = beginningRev > 0 ? (beginningRev + expansionRev - contractionRev - churnRev) / beginningRev : 0;
+  return { label: "NRR", value: val, unit: "%", formula: "(start + exp - contr - churn) / start", inputs: { beginningRev, expansionRev, contractionRev, churnRev } };
+}
+
+export function calcBurnMultiple(netBurn: number, netNewArr: number): QuantResult {
+  const val = netNewArr > 0 ? netBurn / netNewArr : 0;
+  return { label: "Burn Multiple", value: val, unit: "x", formula: "net burn / net new ARR", inputs: { netBurn, netNewArr } };
+}
+
+export function calcMagicNumber(netNewArr: number, priorSMSpend: number): QuantResult {
+  const val = priorSMSpend > 0 ? netNewArr / priorSMSpend : 0;
+  return { label: "Magic Number", value: val, unit: "x", formula: "net new ARR / prior S&M", inputs: { netNewArr, priorSMSpend } };
+}
+
+export function calcRuleOf40(growthPct: number, marginPct: number): QuantResult {
+  const val = growthPct + marginPct;
+  return { label: "Rule of 40", value: val, unit: "%", formula: "growth% + profit margin%", inputs: { growthPct, marginPct } };
+}
+
+export function calcRunway(cash: number, monthlyBurn: number): QuantResult {
+  const val = monthlyBurn > 0 ? cash / monthlyBurn : 0;
+  return { label: "Runway", value: val, unit: "mo", formula: "cash / monthly burn", inputs: { cash, monthlyBurn } };
+}
+
+// ── 8.2.1 Advanced Valuation ─────────────────────────────────────────
+
+export function calcWACC(equityPct: number, costEquity: number, debtPct: number, costDebt: number, taxRate: number): QuantResult {
+  const val = (equityPct * costEquity) + (debtPct * costDebt * (1 - taxRate));
+  return { label: "WACC", value: val, unit: "%", formula: "(E/V * Re) + (D/V * Rd * (1-T))", inputs: { equityPct, costEquity, debtPct, costDebt, taxRate } };
+}
+
+export function calcCAPM(riskFree: number, beta: number, marketPremium: number): QuantResult {
+  const val = riskFree + (beta * marketPremium);
+  return { label: "Cost of Equity", value: val, unit: "%", formula: "Rf + β(Rm - Rf)", inputs: { riskFree, beta, marketPremium } };
+}
+
+export function calcVCMethedPreMoney(exitValue: number, targetIrr: number, yearsToExit: number, dilutionPct: number): QuantResult {
+  const pvExit = exitValue / Math.pow(1 + targetIrr, yearsToExit);
+  const val = pvExit * (1 - dilutionPct);
+  return { label: "VC Pre-money", value: val, unit: "$", formula: "(Exit / (1+IRR)^n) * (1-dilution)", inputs: { exitValue, targetIrr, yearsToExit, dilutionPct } };
+}
+
+// ── 8.12.1 Energy & Signals ──────────────────────────────────────────
+
+export function calcLCOE(lifecycleCost: number, totalEnergy: number): QuantResult {
+  const val = totalEnergy > 0 ? lifecycleCost / totalEnergy : 0;
+  return { label: "LCOE", value: val, unit: "$/MWh", formula: "lifecycle cost / energy generated", inputs: { lifecycleCost, totalEnergy } };
+}
+
+export function calcSharpe(returns: number[], riskFree: number): QuantResult {
+  const avg = returns.reduce((a, b) => a + b, 0) / returns.length;
+  const variance = returns.reduce((a, b) => a + Math.pow(b - avg, 2), 0) / returns.length;
+  const std = Math.sqrt(variance);
+  const val = std > 0 ? (avg - riskFree) / std : 0;
+  return { label: "Sharpe Ratio", value: val, formula: "(Rp - Rf) / σp", inputs: { returns: returns.length, riskFree } };
+}
+
+export function calcKelly(winProb: number, winLossRatio: number): QuantResult {
+  const val = winProb - ((1 - winProb) / winLossRatio);
+  return { label: "Kelly Criterion", value: val, unit: "%", formula: "p - (q/b)", inputs: { winProb, winLossRatio } };
+}

package/src/lib/reportos.ts

@@ -0,0 +1,175 @@
+/**
+ * ReportOS v3 — calculation engines + quality gates.
+ * Real, runnable math (not prose). Every engine returns numeric outputs
+ * plus the formula used, so reports are reproducible and auditable.
+ */
+
+export interface CalcResult {
+  label: string;
+  value: number;
+  unit?: string;
+  formula: string;
+  inputs: Record<string, number>;
+}
+
+// ── 8.1 Market sizing ───────────────────────────────────────────────
+export function calcMarketSizing(i: { customers: number; spendPerCustomer: number; servedShare: number; captureRate: number; }): CalcResult[] {
+  const tam = i.customers * i.spendPerCustomer;
+  const sam = tam * i.servedShare;
+  const som = sam * i.captureRate;
+  return [
+    { label: "TAM", value: tam, unit: "$", formula: "customers × spend/customer", inputs: i },
+    { label: "SAM", value: sam, unit: "$", formula: "TAM × served share", inputs: i },
+    { label: "SOM", value: som, unit: "$", formula: "SAM × capture rate", inputs: i },
+  ];
+}
+export function calcCAGR(begin: number, end: number, years: number): CalcResult {
+  const v = years > 0 && begin > 0 ? Math.pow(end / begin, 1 / years) - 1 : 0;
+  return { label: "CAGR", value: v, unit: "%", formula: "(end/begin)^(1/years) - 1", inputs: { begin, end, years } };
+}
+
+// ── 8.2 Valuation ───────────────────────────────────────────────────
+export function calcNPV(cashflows: number[], rate: number, initial = 0): CalcResult {
+  const npv = cashflows.reduce((acc, cf, t) => acc + cf / Math.pow(1 + rate, t + 1), 0) - initial;
+  return { label: "NPV", value: npv, unit: "$", formula: "Σ FCF_t/(1+r)^t − initial", inputs: { rate, initial, periods: cashflows.length } };
+}
+export function calcIRR(cashflows: number[], initial: number): CalcResult {
+  // bisection on rate in [-0.9, 1.0]
+  const npvAt = (r: number) => cashflows.reduce((a, cf, t) => a + cf / Math.pow(1 + r, t + 1), 0) - initial;
+  let lo = -0.9, hi = 1.0, mid = 0;
+  for (let k = 0; k < 100; k++) {
+    mid = (lo + hi) / 2;
+    const v = npvAt(mid);
+    if (Math.abs(v) < 1e-6) break;
+    if (v > 0) lo = mid; else hi = mid;
+  }
+  return { label: "IRR", value: mid, unit: "%", formula: "rate where NPV = 0 (bisection)", inputs: { initial, periods: cashflows.length } };
+}
+export function calcMOIC(exitEquity: number, investedEquity: number): CalcResult {
+  return { label: "MOIC", value: investedEquity > 0 ? exitEquity / investedEquity : 0, unit: "x", formula: "exit equity / invested equity", inputs: { exitEquity, investedEquity } };
+}
+export function calcAdjEBITDA(i: { reportedEBITDA: number; nonRecurringExp: number; nonRecurringInc: number; runRateAdj: number; }): CalcResult {
+  const v = i.reportedEBITDA + i.nonRecurringExp - i.nonRecurringInc + i.runRateAdj;
+  return { label: "Adjusted EBITDA", value: v, unit: "$", formula: "reported + non-recurring exp − non-recurring inc + run-rate", inputs: i };
+}
+
+// ── 8.3 Scenario / sensitivity ──────────────────────────────────────
+export function calcExpectedValue(scenarios: { p: number; value: number }[]): CalcResult {
+  const ev = scenarios.reduce((a, s) => a + s.p * s.value, 0);
+  return { label: "Expected Value", value: ev, unit: "$", formula: "Σ p × value", inputs: { scenarios: scenarios.length } };
+}
+
+// ── 8.4 Risk scoring ────────────────────────────────────────────────
+export function calcRisk(probability: number, impact: number): CalcResult {
+  return { label: "Risk Score", value: probability * impact, formula: "P × I", inputs: { probability, impact } };
+}
+export function calcResidualRisk(inherent: number, controlEffectiveness: number): CalcResult {
+  return { label: "Residual Risk", value: inherent * (1 - controlEffectiveness), formula: "inherent × (1 − control effectiveness)", inputs: { inherent, controlEffectiveness } };
+}
+export function calcRPN(severity: number, occurrence: number, detectability: number): CalcResult {
+  return { label: "RPN", value: severity * occurrence * detectability, formula: "severity × occurrence × detectability", inputs: { severity, occurrence, detectability } };
+}
+
+// ── 8.5 Evidence confidence ─────────────────────────────────────────
+export function calcConfidence(evidenceStrength: number, methodValidity: number, assumptionStability: number): CalcResult {
+  // claim confidence cannot exceed weakest link
+  const v = Math.min(evidenceStrength, methodValidity, assumptionStability);
+  return { label: "Claim Confidence", value: v, unit: "/100", formula: "min(evidence, method, assumption)", inputs: { evidenceStrength, methodValidity, assumptionStability } };
+}
+
+// ── 8.6 Research statistics ─────────────────────────────────────────
+export function calcEffectSize(meanDiff: number, pooledSD: number): CalcResult {
+  return { label: "Effect Size (d)", value: pooledSD > 0 ? meanDiff / pooledSD : 0, formula: "mean diff / pooled SD", inputs: { meanDiff, pooledSD } };
+}
+export function calcRelativeRisk(treatmentRisk: number, controlRisk: number): CalcResult {
+  return { label: "Relative Risk", value: controlRisk > 0 ? treatmentRisk / controlRisk : 0, formula: "treatment risk / control risk", inputs: { treatmentRisk, controlRisk } };
+}
+
+// ── 8.7 Policy cost-benefit ─────────────────────────────────────────
+export function calcCostBenefit(pvBenefits: number, pvCosts: number): CalcResult[] {
+  return [
+    { label: "Benefit-Cost Ratio", value: pvCosts > 0 ? pvBenefits / pvCosts : 0, formula: "PV(benefits) / PV(costs)", inputs: { pvBenefits, pvCosts } },
+    { label: "Net Social Benefit", value: pvBenefits - pvCosts, unit: "$", formula: "PV(benefits) − PV(costs)", inputs: { pvBenefits, pvCosts } },
+  ];
+}
+
+// ── 8.8 ESG / climate ───────────────────────────────────────────────
+export function calcGHG(scope1: number, scope2: number, scope3: number): CalcResult {
+  return { label: "Total GHG", value: scope1 + scope2 + scope3, unit: "tCO₂e", formula: "Scope 1 + 2 + 3", inputs: { scope1, scope2, scope3 } };
+}
+export function calcCarbonIntensity(tco2e: number, revenue: number): CalcResult {
+  return { label: "Carbon Intensity", value: revenue > 0 ? tco2e / revenue : 0, unit: "tCO₂e/$", formula: "tCO₂e / revenue", inputs: { tco2e, revenue } };
+}
+
+// ── 8.9 Digital / AI readiness ──────────────────────────────────────
+export function calcAIReadiness(i: { dataQuality: number; infra: number; talent: number; governance: number; process: number; change: number; }): CalcResult {
+  const v = 0.25 * i.dataQuality + 0.20 * i.infra + 0.20 * i.talent + 0.15 * i.governance + 0.10 * i.process + 0.10 * i.change;
+  return { label: "AI Readiness", value: v, unit: "/100", formula: "0.25·data + 0.20·infra + 0.20·talent + 0.15·gov + 0.10·process + 0.10·change", inputs: i };
+}
+
+// ── 8.11 Pricing ────────────────────────────────────────────────────
+export function calcPocketPrice(list: number, discounts: number, rebates: number, promos: number, leakage: number): CalcResult {
+  return { label: "Pocket Price", value: list - discounts - rebates - promos - leakage, unit: "$", formula: "list − discounts − rebates − promos − leakage", inputs: { list, discounts, rebates, promos, leakage } };
+}
+
+// ── 8.12 Energy LCOE ────────────────────────────────────────────────
+export function calcLCOE(pvLifecycleCosts: number, pvEnergyMWh: number): CalcResult {
+  return { label: "LCOE", value: pvEnergyMWh > 0 ? pvLifecycleCosts / pvEnergyMWh : 0, unit: "$/MWh", formula: "PV(lifecycle costs) / PV(energy)", inputs: { pvLifecycleCosts, pvEnergyMWh } };
+}
+
+// ── Quality gates (Section 9) ───────────────────────────────────────
+export interface QuantResult { label: string; value: number; unit?: string; formula: string; inputs: Record<string, number>; }
+export interface QualityGate { id: string; name: string; check: string; }
+export const QUALITY_GATES: QualityGate[] = [
+  { id: "G1", name: "Objective fit", check: "Every section supports the stated decision/question/objective" },
+  { id: "G2", name: "Evidence binding", check: "Every factual claim links to source, data, calculation, or explicit assumption" },
+  { id: "G3", name: "Status labeling", check: "Facts ≠ assumptions ≠ forecasts ≠ recommendations" },
+  { id: "G4", name: "MECE structure", check: "Categories non-overlapping, no gaps, same logical level" },
+  { id: "G5", name: "Calculation reproducibility", check: "Numbers show formula, inputs, assumptions, sensitivity" },
+  { id: "G6", name: "Falsification / red-team", check: "What would make the recommendation wrong; what data reverses it" },
+  { id: "G7", name: "Compliance", check: "Satisfies applicable standard (NIH/NSF/GAO/PRISMA/SEC/CSRD/NIST AI RMF)" },
+  { id: "G8", name: "Audience density", check: "Exec decides from summary; analyst reproduces from appendix" },
+];
+
+// ── Archetype routing (Section 4 + Step 2) ──────────────────────────
+export type ArchetypeId =
+  | "decision-strategy" | "investment-financial" | "implementation-tech"
+  | "audit-assurance" | "scientific-academic" | "policy-public" | "market-commercial";
+
+export interface Archetype { id: ArchetypeId; name: string; covers: string; sections: string[]; }
+
+export const ARCHETYPES: Archetype[] = [
+  { id: "decision-strategy", name: "Decision / Strategy", covers: "McKinsey, BCG, Bain, Strategy&, EY-Parthenon strategy, Roland Berger, Innosight, market entry, growth strategy",
+    sections: ["Decision Summary", "Situation / Context", "Core Question", "Evidence & Diagnosis", "Strategic Options", "Recommendation", "Business Case", "Implementation Roadmap", "Risk & Falsification", "Appendix"] },
+  { id: "investment-financial", name: "Investment / Transaction / Financial", covers: "Bain PE diligence, EY-Parthenon CDD, Deloitte/PwC transaction services, QofE, AlixPartners restructuring, equity research, IC memos",
+    sections: ["Investment / Transaction Thesis", "Target / Asset Overview", "Market & Competitive Assessment", "Commercial Diligence", "Financial Diligence", "Value Creation Plan", "Valuation", "Risks & Deal Protections", "Decision Package", "Appendix"] },
+  { id: "implementation-tech", name: "Implementation / Technology / Transformation", covers: "Accenture, Deloitte Digital, IBM, Capgemini, digital/AI transformation, cloud migration, ERP, cyber modernization",
+    sections: ["Transformation Summary", "Current-State Assessment", "Target-State Blueprint", "Use Case / Initiative Portfolio", "Operating Model", "Roadmap", "Business Case", "Risk, Security & Responsible AI", "Adoption & Change", "Appendix"] },
+  { id: "audit-assurance", name: "Audit / Assurance / Risk / Compliance", covers: "KPMG risk advisory, Big 4 audit, internal audit, GAO/IG audit, cyber incident, FTI forensic, ERM",
+    sections: ["Executive Assurance Summary", "Scope & Criteria", "Methodology", "Finding Register", "Risk Assessment", "Control / Compliance Matrix", "Recommendations & Remediation", "Governance & Tracking", "Appendix"] },
+  { id: "scientific-academic", name: "Scientific / Academic / Evidence-Synthesis", covers: "IMRAD article, NIH R01/RPPR, NSF proposal, dissertation, PRISMA review, RAND research, policy research",
+    sections: ["Research Summary", "Background & Gap", "Objectives / Aims", "Methods", "Results / Preliminary Data", "Interpretation / Discussion", "Impact / Broader Significance", "Compliance & Reporting", "References", "Supplementary"] },
+  { id: "policy-public", name: "Policy / Public Sector / Multilateral", covers: "GAO program evaluation, CRS, OMB memo, World Bank, IMF, OECD, UNDP, EC impact assessment, think tanks",
+    sections: ["Policy Summary", "Mandate / Context", "Diagnostic", "Evidence & Comparative Analysis", "Policy Options", "Impact Analysis", "Preferred Option / Recommendations", "Implementation & Governance", "Annexes"] },
+  { id: "market-commercial", name: "Market / Sector / Commercial Intelligence", covers: "Market entry, industry outlook, ESG strategy, healthcare ops, real estate, pricing strategy, HR benchmarking, energy/climate",
+    sections: ["Market / Sector Summary", "Market Definition", "Market Sizing & Growth", "Demand & Customer Analysis", "Competitive Landscape", "Economics", "Trends & Disruption", "Strategic Implications", "Appendix"] },
+];
+
+const ARCH_ROUTES: { re: RegExp; id: ArchetypeId }[] = [
+  { re: /\b(invest|acquir|due diligence|valuation|ebitda|m&a|buyout|equity research|restructur|10-?k)\b/i, id: "investment-financial" },
+  { re: /\b(audit|assurance|compliance|controls|finding|forensic|incident|erm|gagas|yellow book)\b/i, id: "audit-assurance" },
+  { re: /\b(transform|modernize|architecture|migration|cloud|erp|implementation|devops|mlops)\b/i, id: "implementation-tech" },
+  { re: /\b(grant|hypothesis|study|trial|systematic review|prisma|nih|nsf|imrad|dissertation|meta-analysis)\b/i, id: "scientific-academic" },
+  { re: /\b(policy|public sector|world bank|imf|oecd|undp|legislation|regulation impact|cost-benefit|program evaluation)\b/i, id: "policy-public" },
+  { re: /\b(market size|tam|sam|som|industry outlook|pricing|esg|sustainability|lcoe|sector|benchmark)\b/i, id: "market-commercial" },
+  { re: /\b(strateg|recommend|should we|grow|options|board|decision)\b/i, id: "decision-strategy" },
+];
+
+export function routeArchetype(query: string): ArchetypeId {
+  for (const r of ARCH_ROUTES) if (r.re.test(query)) return r.id;
+  return "decision-strategy";
+}
+
+export function findArchetype(id: ArchetypeId): Archetype {
+  return ARCHETYPES.find(a => a.id === id) ?? ARCHETYPES[0];
+}