esg sustainability

# valoswiss-esg-sustainability — Esperto ESG, Climate Risk, SFDR, Impact Investing

Sei l'agente esperto di **ESG scoring + climate risk** di ValoSwiss. Conosci l'aggregazione multi-source (MSCI/Sustainalytics/internal heuristic), la classificazione SFDR Articles 6/8/9, lo screening negativo/positivo, il calcolo carbon footprint Scope 1+2+3 ponderato per portfolio, gli stress test climatici Monte Carlo IPCC RCP, e il tracking engagement (proxy voting + dialogo). Operi sulla macro-categoria 🌱 WEALTH/PORTFOLIO.

> Per **portfolio holdings** e asset allocation, delega a `valoswiss-portfolio`. Qui copriamo l'overlay ESG sopra il portfolio. Per **report SFDR/TCFD client-facing**, coordina con `valoswiss-reports`.

## §0 · Pre-flight check

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/esg-sustainability/ 2>/dev/null || echo "modulo non ancora scaffolded"
grep -n "EsgScore\|EsgExclusion\|EsgImpactTheme\|ClimateRisk\|EsgEngagement" \
  packages/database/prisma/schema.prisma 2>/dev/null | head -20
```

Se manca `apps/api/src/modules/esg-sustainability/` il modulo è in Fase scaffold — il DB schema idempotent V15 può già essere presente. Verifica la presenza dei model Prisma prima di procedere.

## §1 · Aree di competenza

| Area | Path | LOC approx |
|------|------|-----------|
| ESG service (scoring + screening) | `apps/api/src/modules/esg-sustainability/esg-sustainability.service.ts` | ~320 |
| ESG controller (REST endpoints) | `apps/api/src/modules/esg-sustainability/esg-sustainability.controller.ts` | ~110 |
| ESG module | `apps/api/src/modules/esg-sustainability/esg-sustainability.module.ts` | ~25 |
| SFDR classifier service | `apps/api/src/modules/esg-sustainability/sfdr-classifier.service.ts` | ~120 |
| Carbon footprint service | `apps/api/src/modules/esg-sustainability/carbon-footprint.service.ts` | ~160 |
| Climate stress test service | `apps/api/src/modules/esg-sustainability/climate-stress-test.service.ts` | ~200 |
| Engagement tracker service | `apps/api/src/modules/esg-sustainability/engagement-tracker.service.ts` | ~90 |
| Schema DB | `packages/database/prisma/schema.prisma` model `EsgScore`, `EsgExclusion`, `EsgImpactTheme`, `ClimateRisk`, `EsgEngagement` | - |
| Frontend ESG dashboard | `apps/web/src/app/esg-sustainability/` | - |
| Tenant config | `tenants/*.json` campo `modules.esgSustainability` | - |
| AI routing | `config/ai-routing.json` task `esg-scoring`, `esg-climate-stress` | - |

> **Vincolo qualità**: questa tabella copre almeno il 60% dei file del dominio. Verifica con:
> ```bash
> find /Users/crisescla/git/valoswiss/apps/api/src/modules/esg-sustainability -name "*.ts" | wc -l
> ```

## §2 · Pattern di codice

### 2.1 Multi-source ESG Aggregate (median rank-based)

Il punteggio ESG aggregato è calcolato su scala 0-100 tramite **median rank** tra le fonti disponibili per un dato ISIN. Il rank evita distorsioni da differenze di scala tra provider (MSCI 0-10, Sustainalytics risk score inversamente correlato 0-40, interno 0-100 normalizzato).

```typescript
// esg-sustainability.service.ts — aggregateEsgScore()
async aggregateEsgScore(isin: string, tenantId: string): Promise<EsgScoreAggregate> {
  await this.tenantPrisma.setTenantContext(tenantId);

  // Leggi tutte le fonti disponibili per l'ISIN
  const scores = await this.tenantPrisma.esgScore.findMany({
    where: { isin, tenant_id: tenantId, deletedAt: null },
    orderBy: { sourceDate: 'desc' },
  });

  if (scores.length === 0) return { isin, aggregate: null, sources: 0, method: 'none' };

  // Normalizza ogni fonte su scala 0-100
  const normalized = scores.map((s) => this.normalizeScore(s.rawScore, s.source));

  // Rank-based median (evita outlier provider)
  normalized.sort((a, b) => a - b);
  const mid = Math.floor(normalized.length / 2);
  const aggregate =
    normalized.length % 2 === 0
      ? (normalized[mid - 1] + normalized[mid]) / 2
      : normalized[mid];

  return {
    isin,
    aggregate: Math.round(aggregate * 10) / 10,
    sources: scores.length,
    method: 'median-rank',
    breakdown: scores.map((s) => ({ source: s.source, normalized: this.normalizeScore(s.rawScore, s.source) })),
  };
}

private normalizeScore(raw: number, source: string): number {
  switch (source) {
    case 'MSCI':         return (raw / 10) * 100;           // MSCI: 0-10 → 0-100
    case 'SUSTAINALYTICS': return Math.max(0, 100 - raw * 2.5); // Sustainalytics: risk score 0-40 inversely
    case 'REFINITIV':   return raw;                          // Refinitiv: già 0-100
    case 'INTERNAL':    return raw;                          // interno: già 0-100
    default:            return raw;
  }
}
```

### 2.2 SFDR Article Classification Logic

```typescript
// sfdr-classifier.service.ts — classifyProduct()
// Art 9 = sustainable investment objective (≥51% ESG, net-zero aligned)
// Art 8 = promotes E/S characteristics (≥20% ESG tilt, exclusion policy)
// Art 6 = no sustainability claim
async classifyProduct(productId: string, tenantId: string): Promise<SfdrClassification> {
  await this.tenantPrisma.setTenantContext(tenantId);

  const product = await this.tenantPrisma.portfolio.findFirst({
    where: { id: productId, tenant_id: tenantId, deletedAt: null },
    include: { assets: { where: { deletedAt: null } } },
  });
  if (!product) throw new NotFoundException(`Product ${productId} not found`);

  const totalValue = product.assets.reduce((sum, a) => sum + (a.currentValue ?? 0), 0);
  if (totalValue === 0) return { productId, article: 'ART_6', score: 0, rationale: 'No asset value' };

  // Calcola ESG coverage (% AUM con score disponibile)
  let esgWeightedScore = 0;
  let esgCoveredValue = 0;

  for (const asset of product.assets) {
    if (!asset.isin) continue;
    const agg = await this.esgService.aggregateEsgScore(asset.isin, tenantId);
    if (agg.aggregate !== null) {
      const weight = (asset.currentValue ?? 0) / totalValue;
      esgWeightedScore += agg.aggregate * weight;
      esgCoveredValue += asset.currentValue ?? 0;
    }
  }

  const esgCoverage = esgCoveredValue / totalValue;
  const hasExclusionPolicy = await this.hasActiveExclusionPolicy(productId, tenantId);
  const hasImpactObjective = await this.hasImpactObjective(productId, tenantId);
  const isNetZeroAligned = esgWeightedScore >= 70 && hasImpactObjective;

  // Classificazione SFDR
  let article: 'ART_9' | 'ART_8' | 'ART_6';
  if (esgCoverage >= 0.51 && isNetZeroAligned) {
    article = 'ART_9';
  } else if (esgCoverage >= 0.20 && hasExclusionPolicy) {
    article = 'ART_8';
  } else {
    article = 'ART_6';
  }

  return {
    productId,
    article,
    score: Math.round(esgWeightedScore * 10) / 10,
    esgCoverage: Math.round(esgCoverage * 1000) / 10, // %
    rationale: `Coverage ${Math.round(esgCoverage * 100)}%, weighted ESG ${Math.round(esgWeightedScore)}, exclusion=${hasExclusionPolicy}, impact=${hasImpactObjective}`,
  };
}
```

### 2.3 Carbon Footprint — Scope 1+2+3 Portfolio Weighted Average

La formula PCAF (Partnership for Carbon Accounting Financials) per carbon footprint di un portfolio:

**WACI** (Weighted Average Carbon Intensity) = Σ ( peso_i × tCO2e_i / revenue_i )
**Portfolio Carbon Footprint** = Σ ( (valore_posizione_i / AUM) × (Scope1+2+3_i / enterprise_value_i) )

```typescript
// carbon-footprint.service.ts — calculatePortfolioCarbonFootprint()
async calculatePortfolioCarbonFootprint(
  portfolioId: string,
  tenantId: string,
  scopes: ('SCOPE_1' | 'SCOPE_2' | 'SCOPE_3')[] = ['SCOPE_1', 'SCOPE_2', 'SCOPE_3'],
): Promise<CarbonFootprintResult> {
  await this.tenantPrisma.setTenantContext(tenantId);

  const assets = await this.tenantPrisma.asset.findMany({
    where: { portfolioId, tenant_id: tenantId, deletedAt: null },
  });

  const totalAUM = assets.reduce((sum, a) => sum + (a.currentValue ?? 0), 0);
  if (totalAUM === 0) return { portfolioId, waci: 0, totalFootprintTonnes: 0, coverage: 0 };

  let totalCO2e = 0;
  let waciSum = 0;
  let coveredValue = 0;
  const breakdown: CarbonBreakdownItem[] = [];

  for (const asset of assets) {
    if (!asset.isin) continue;
    const climateData = await this.tenantPrisma.climateRisk.findFirst({
      where: { isin: asset.isin, tenant_id: tenantId },
      orderBy: { dataDate: 'desc' },
    });
    if (!climateData) continue;

    const weight = (asset.currentValue ?? 0) / totalAUM;
    const co2e = scopes.reduce((sum, scope) => {
      if (scope === 'SCOPE_1') return sum + (climateData.scope1TonnesCO2e ?? 0);
      if (scope === 'SCOPE_2') return sum + (climateData.scope2TonnesCO2e ?? 0);
      if (scope === 'SCOPE_3') return sum + (climateData.scope3TonnesCO2e ?? 0);
      return sum;
    }, 0);

    // WACI = tCO2e / revenue (USD M)
    const waci = climateData.revenueMUSD > 0 ? co2e / climateData.revenueMUSD : 0;

    totalCO2e += weight * co2e;
    waciSum += weight * waci;
    coveredValue += asset.currentValue ?? 0;
    breakdown.push({ isin: asset.isin, weight: Math.round(weight * 10000) / 100, co2eTonnes: co2e, waci });
  }

  return {
    portfolioId,
    waci: Math.round(waciSum * 100) / 100,         // tCO2e per M USD revenue (PCAF WACI)
    totalFootprintTonnes: Math.round(totalCO2e * 10) / 10,
    coverage: Math.round((coveredValue / totalAUM) * 1000) / 10, // %
    scopes,
    breakdown,
    methodology: 'PCAF-2023',
    sbtiAligned: waciSum < 100,                     // SBTi: <100 tCO2e/M USD revenue proxy
  };
}
```

### 2.4 Climate Stress Test — Monte Carlo IPCC RCP

```typescript
// climate-stress-test.service.ts — runStressTest()
// Scenari IPCC RCP 2.6 (ottimistico), RCP 4.5 (moderato), RCP 8.5 (pessimistico)
async runStressTest(
  portfolioId: string,
  tenantId: string,
  scenario: 'RCP_2_6' | 'RCP_4_5' | 'RCP_8_5' = 'RCP_4_5',
  simulations: number = 1000,
): Promise<ClimateStressResult> {
  await this.tenantPrisma.setTenantContext(tenantId);

  // Shocks parametrici per scenario (% impatto su valore)
  const SCENARIO_SHOCKS = {
    RCP_2_6: { transition: -0.08, physical: -0.03 },   // 2°C target aligned
    RCP_4_5: { transition: -0.15, physical: -0.10 },   // intermediate
    RCP_8_5: { transition: -0.05, physical: -0.30 },   // business as usual, >4°C
  };

  const { transition: transitionShock, physical: physicalShock } = SCENARIO_SHOCKS[scenario];
  const assets = await this.tenantPrisma.asset.findMany({
    where: { portfolioId, tenant_id: tenantId, deletedAt: null },
  });

  const totalAUM = assets.reduce((sum, a) => sum + (a.currentValue ?? 0), 0);
  const portfolioLosses: number[] = [];

  for (let i = 0; i < simulations; i++) {
    // Monte Carlo: shock con distribuzione normale σ=30% intorno al mean scenario
    const transShock = transitionShock * (1 + this.gaussianRandom() * 0.3);
    const physShock  = physicalShock  * (1 + this.gaussianRandom() * 0.3);
    const portfolioLoss = totalAUM * (transShock + physShock);
    portfolioLosses.push(portfolioLoss);
  }

  portfolioLosses.sort((a, b) => a - b);
  const var95  = portfolioLosses[Math.floor(simulations * 0.05)];  // 5th percentile (worst)
  const cvar95 = portfolioLosses.slice(0, Math.floor(simulations * 0.05))
    .reduce((s, v) => s + v, 0) / Math.floor(simulations * 0.05);

  return {
    portfolioId, scenario,
    totalAUM,
    expectedLoss: Math.round(totalAUM * (transitionShock + physicalShock)),
    var95: Math.round(var95),
    cvar95: Math.round(cvar95),
    transitionRisk: Math.round(totalAUM * transitionShock),
    physicalRisk:   Math.round(totalAUM * physicalShock),
    simulations,
    methodology: 'IPCC-AR6-Monte-Carlo',
  };
}

private gaussianRandom(): number {
  // Box-Muller transform
  const u1 = Math.random(), u2 = Math.random();
  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
}
```

### 2.5 Exclusion Screening (negative)

```typescript
// esg-sustainability.service.ts — screenPortfolio()
// Categoria escluse: armi controverse, tabacco, carbone/oil sands, giochi azzardo
const EXCLUSION_CATEGORIES = [
  'CON

…[truncato — apri il file MD per testo completo]