execution engine

# valoswiss-execution-engine (📈 QUANT/MARKETS)

**Macro-categoria**: 📈 QUANT/MARKETS
**Scope**: Order execution algorithms VWAP/TWAP/POV/Iceberg + Smart Order Routing + Slippage + TCA
**Phase**: PROTOTYPE-PHASE (paper-trading default; live richiede MIFID II + FINMA approval downstream)
**Sidecar Port**: 8898 (FastAPI Nautilus subset + ccxt + freqtrade primitives)
**Owner downstream**: ADVISOR (paper orders proprie) · SUPERVISOR/ADMIN (cross-tenant + algo config + TCA)
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento sull'execution-engine, verifica in quest'ordine:

1. **Branch + working tree pulito**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Sidecar Python execution-engine health**
   ```bash
   curl -s http://127.0.0.1:8898/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"...","paperMode":true,"engines":{"nautilus":"available","ccxt":"available","freqtrade":"primitives-only"}}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep execution-engine-py`.
3. **NestJS proxy health**
   ```bash
   curl -s http://127.0.0.1:4010/api/execution/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok', paperMode:true}, circuitBreaker:{state:'closed', failures:0}, ledger:{lastFillAt: ...} }`.
4. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le 4 model `ExecutionOrder` / `ExecutionFill` / `ExecutionAlgo` / `ExecutionTCA` + 3 enum `ExecutionOrderStatus` / `ExecutionAlgoType` / `ExecutionVenue` siano applicati (idempotent V15).
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"executionEngine": false` in fase prototipo (default false; SUPERVISOR/ADMIN abilita on-demand). Subito dopo `tradingAgents`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'executionEngine'` in `defaultModules` SOLO per `ADVISOR` + `RELATIONSHIP_MANAGER` + `SUPERVISOR` + `ADMIN`. **NON** in CLIENT-facing packs (CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL → MIFID II + FINMA).
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `executionEngine` con `sidebarSection: 'OPERARE'`, `requiredRole: 'ADVISOR'`, `personaHint: 'execution'`, icon `📈`, tag `PROTOTYPE-PAPER-MODE`.
8. **Paper mode flag globale**:
   ```bash
   echo $EXECUTION_LIVE_ENABLED  # deve essere "0" o vuoto in prototipo
   echo $EXECUTION_PAPER_DEFAULT # deve essere "1"
   ```
   Se `EXECUTION_LIVE_ENABLED=1` senza approval MIFID/FINMA documentata → STOP immediato.
9. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §3), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic`. Phase MAJOR (peso 8) in prototipo; phase CRITICAL post-prototipo.

Se uno qualunque dei 9 punti fallisce → **fermati e annota la deviazione**. La 3-Point Registration V16 è invariante non negoziabile (vedi `feedback_new_module_registration.md`).

---

## §1 · Aree di competenza

### 1.1 Algoritmi di esecuzione (institutional-grade)

| Algo | Obiettivo | Slicing logic | Use case |
|---|---|---|---|
| **VWAP** | Volume-weighted avg price ≤ benchmark VWAP intraday | Slice size ∝ historical volume curve (U-shape) | Large equity orders (>1% ADV), benchmark-tracking |
| **TWAP** | Time-weighted avg price (equal slice in time) | N slice equi-distanziati su window [t0, t1] | Mid-cap, low-volume, no urgency |
| **POV** (Percent of Volume) | Mantiene participation rate target su tape live | Adaptive: pct_target × tape_volume_window | Volatile mkt, liquidity-tracking |
| **Iceberg** | Hidden total qty, expose only tip per execution | Expose visible_qty; refill on fill until total reached | Block trades senza impact |
| **Implementation Shortfall** (Almgren-Chriss) | Min costo totale = market impact + risk variance | Optimal trajectory via λ risk-aversion | Urgent + risk-aware |
| **Sniper** | Aggressive cross spread quando liquidity appare | Listen book L1, lift offer / hit bid quando size match | Opportunistic, small qty |
| **Market-on-Close** (MOC) | Execute at official closing auction | Submit MOC order pre-cutoff (NYSE 15:50) | Index funds rebalancing |

### 1.2 Smart Order Routing (SOR) multi-venue

In prototipo: **paper-mode SOR** simulato su book aggregato sintetico (top 5 venue per asset class). Logica:
1. Quote consolidation L1 (NBBO equity / BBO crypto)
2. Routing decision: best price + venue fees + fill probability
3. Child orders dispatch (paper) verso venue picks
4. Fill aggregation + parent order update

Venue supportate (paper-mode):
- **Equity**: NYSE, NASDAQ, BATS, IEX, ARCA (sintetici)
- **Crypto** (via ccxt): Binance, Coinbase, Kraken, Bitstamp, OKX
- **FX**: simulato top-of-book multi-bank
- **Bond**: TRACE-style synthetic (no live feed in prototipo)

### 1.3 Slippage modeling

Modelli supportati per pre-trade estimate + post-trade attribution:
- **Linear impact** (Kissell-Glantz): `slippage = α × σ × sqrt(qty / ADV)`
- **Square-root impact** (Almgren): `slippage = γ × σ × (qty / V_daily)^0.5`
- **Spread-cross cost**: `0.5 × spread × qty` (passive→aggressive switch)
- **Latency cost** (HFT): `latency_ms × volatility_per_ms × qty`
- **Adverse selection**: post-fill markout 1s/5s/30s

### 1.4 Transaction Cost Analysis (TCA) post-trade

Per ogni ordine completato (paper o live):
- **Implementation Shortfall**: `(fillVWAP - decisionPrice) × side × qty`
- **VWAP slippage**: `(fillVWAP - intervalVWAP) / intervalVWAP × bps`
- **Arrival price slippage**: `(fillVWAP - arrivalPrice) / arrivalPrice × bps`
- **Markout 1s / 5s / 30s / 5min** post-fill
- **Venue attribution**: cost split per venue child fill
- **Algo attribution**: cost decomposition (impact + timing + opportunity)

### 1.5 Persona visibility (PROTOTYPE-PHASE)

- **ADVISOR** (ws+az): paper orders proprie + drill-down TCA proprie esecuzioni
- **RELATIONSHIP_MANAGER**: idem ADVISOR
- **SUPERVISOR/ADMIN**: cross-tenant + algo config + TCA aggregato + paper/live toggle (richiede approval MIFID/FINMA documentata)
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO assoluto. Execution endpoint NON accessibili a persona client-facing per MIFID II + FINMA Swiss compliance.

Enforcement multi-livello:
1. NestJS `@Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')` decorator
2. Persona pack `executionEngine` NON in defaultModules client packs
3. Module registry `requiredRole: 'ADVISOR'` (sidebar invisibile a client)
4. Tenant config flag `executionEngine: false` default in prototipo
5. R-Audit rule `EXECUTION-PAPER-MODE-VIOLATION.md` MAJOR signal

---

## §2 · Pattern di codice

### 2.1 VWAP slicing schedule (Python sidecar `services/execution-engine-py/algos/vwap.py`)

```python
from __future__ import annotations
from dataclasses import dataclass
from datetime import datetime, time, timedelta
from typing import Sequence

@dataclass
class VwapSchedule:
    slice_times: list[datetime]
    slice_qtys: list[float]
    total_qty: float
    benchmark_vwap_estimate: float

# U-shape historical volume curve typical equity intraday:
# higher at open + close, lower midday
DEFAULT_VOLUME_CURVE_BPS = [
    180, 140, 90, 70, 60, 55, 50, 50, 55, 60, 70, 90, 140, 180  # 30-min buckets, sums to ~1290 bps
]

def build_vwap_schedule(
    total_qty: float,
    start: datetime,
    end: datetime,
    volume_curve_bps: Sequence[int] = DEFAULT_VOLUME_CURVE_BPS,
    bucket_minutes: int = 30,
) -> VwapSchedule:
    """Slicing pesato sulla curva volume storica.
    Sum(curve) normalized → fraction × total_qty per bucket.
    """
    total_curve = sum(volume_curve_bps)
    total_minutes = int((end - start).total_seconds() / 60)
    n_buckets = max(1, total_minutes // bucket_minutes)
    # interpolate / truncate curve to n_buckets
    if n_buckets <= len(volume_curve_bps):
        curve = list(volume_curve_bps[:n_buckets])
    else:
        # repeat tail bucket (assume mid-day flat extension)
        curve = list(volume_curve_bps) + [volume_curve_bps[-1]] * (n_buckets - len(volume_curve_bps))
    curve_sum = sum(curve)
    slice_qtys = [total_qty * (b / curve_sum) for b in curve]
    slice_times = [start + timedelta(minutes=i * bucket_minutes) for i in range(n_buckets)]
    return VwapSchedule(
        slice_times=slice_times,
        slice_qtys=slice_qtys,
        total_qty=total_qty,
        benchmark_vwap_estimate=0.0,  # filled post-execution
    )
```

### 2.2 TWAP equal-time slice (Python sidecar `algos/twap.py`)

```python
from __future__ import annotations
from datetime import datetime, timedelta
from dataclasses import dataclass

@dataclass
class TwapSchedule:
    slice_times: list[datetime]
    slice_qty: float
    total_qty: float
    n_slices: int

def build_twap_schedule(
    total_qty: float,
    start: datetime,
    end: datetime,
    n_slices: int = 12,
) -> TwapSchedule:
    """Equal-time slicing. n_slices default 12 (every 5min su 1h)."""
    if n_slices <= 0:
        raise ValueError("n_slices must be positive")
    total_seconds = (end - start).total_seconds()
    if total_seconds <= 0:
        raise ValueError("end must be after start")
    interval = timedelta(seconds=total_seconds / n_slices)
    slice_times = [start + interval * i for i in range(n_slices)]
    slice_qty = total_qty / n_slices
    return TwapSchedule(
        slice_times=slice_times,
        slice_qty=slice_qty,
        total_qty=total_qty,
        n_slices=n_slices,
    )
```

### 2.3 POV adaptive (Python sidecar `algos/pov.py`)

```python
from __future__ import annotations
from dataclasses import dataclass

@dataclass
class PovState:
    target_pct: float       # es. 0.10 = 10%
    executed_qty: float
    total_qty: float
    tape_volume_observed: float

def next_pov_slice_qty(state: PovState, tape_volume_window: float) -> float:
    """Adaptive: child qty = target_pct × tape_volume_window, capped da remaining."""
    remaining = state.total_qty - state.executed_qty
    if remaining <= 0:
        return 0.0
    desired = state.target_pct * tape_volume_window
    return max(0.0, min(desired, remaining))
```

### 2.4 Iceberg refill (Python sidecar `algos/iceberg.py`)

```python
from __future__ import annotations
from dataclasses import dataclass

@dataclass
class IcebergState:
    total_qty: float
    visible_qty: float       # tip esposto per slice
    executed_qty: float
    n_refills: int

def refill_iceberg(state: IcebergState, last_fill_qty: float) -> tuple[IcebergState, float]:
    """Dopo fill del tip esposto, refilla con nuovo tip se total non raggiunto.
    Ritorna nuovo state + qty da esporre (0 se completed)."""
    new_executed = state.executed_qty + last_fill_qty
    remaining = state.total_qty - new_executed
    if remaining <= 0:
        return (
            IcebergState(state.total_qty, state.visible_qty, new_executed, state.n_refills),
            0.0,
        )
    next_tip = min(state.visible_qty, remaining)
    return (
        IcebergState(state.total_qty, state.visible_qty, new_executed, state.n_refills + 1),
        next_tip,
    )
```

### 2.5 Implementation Shortfall (Almgren-Chriss) — esempio scheletro

```python
from __future__ import annotations
import math
from dataclasses import dataclass

@dataclass
class AlmgrenChrissParams:
    total_qty: float
    horizon_seconds: float
    sigma: float          # vol per second
    eta: float            # temporary impact coeff
    gamma: float          # permanent impact coeff
    lambda_risk: float    # risk-aversion (higher → faster execution)

def is_optimal_trajectory(p: AlmgrenChrissParams, n_steps: int) -> list[float]:
    """Optimal Almgren-Chriss trajectory: hyperbolic-sin form per minimizzare
    market impact + risk variance.
    """
    if p.lambda_risk <= 0:
        # No risk aversion → linear (TWAP equivalente)
      

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