sentiment-engine/prod/exec_unified/friction.py

"""Friction telemetry — "before-and-after or it didn't happen" (spec §12).

This is the instrument that turns "smart exec is better" from a claim into a number. It
computes, per resolved order, the effective friction in basis points (adverse slippage vs
the caller's guideline price + realized fee) and the savings vs the naive-MARKET baseline a
T0 flight would have paid. Aggregated per urgency class, that IS the §15 rung-by-rung delta
and simultaneously MALKHUT's reward signal (§5-3) — one instrument, two consumers.

TWO LAWS this module exists to honor, both learned the hard way:

  * §13 / §4-5 — **telemetry is a lossless SIDE-LANE and is NEVER allowed on the exec path.**
    (b46ebd2: a telemetry write on the hot path is a latent stall/raise in the order loop.)
    So ``FrictionJournal.record`` catches everything and CANNOT raise. A dead sink loses a
    telemetry row; it never touches an order. The pure bps math *can* raise (bad reference
    price is a programming error) — but only ever inside record()'s guard, off the exec path.

  * BingX commission SIGN — a NEGATIVE commission is a COST/debit (opposite Binance);
    a positive one is a rebate. We paid for this: omp read −2.00 bps as a "rebate" when it
    was a +2.00 bps cost. ``fee_cost_from_commission`` encodes the flip so no caller repeats
    it. See [[bingx_maker_fee_and_commission_sign]].

Pure stdlib + Decimal. No I/O of its own; the CH sink is injected.
"""
from __future__ import annotations

import logging
from dataclasses import dataclass, field
from decimal import Decimal
from typing import Callable

from .contract import Side, UrgencyClass

LOGGER = logging.getLogger(__name__)

# Measured venue rates (VST, 2026-07-14) — [[bingx_maker_fee_and_commission_sign]].
# Maker = 2.00 bps (refutes the 1 bp savings-table assumption); taker = 5.016 bps over 1,455 fills.
MAKER_FEE_BPS = Decimal("2.00")
TAKER_FEE_BPS = Decimal("5.016")
_BPS = Decimal("10000")


def fee_cost_from_commission(commission: Decimal) -> Decimal:
    """Venue commission → signed COST in quote currency (positive = we paid).

    BingX reports commission NEGATIVE for a debit (a cost) and positive for a rebate — the
    opposite of Binance. Cost is therefore ``-commission``: a −0.013 commission is a +0.013
    cost; a +0.005 rebate is a −0.005 cost (we earned it). The one-line flip that omp's Q1
    got backwards. THE mutation test: change this to ``return commission`` and the sign test
    goes RED.
    """
    return -commission


def adverse_slippage_bps(guideline_px: Decimal, fill_px: Decimal, side: Side) -> Decimal:
    """Signed slippage of the fill vs the caller's guideline, in bps. POSITIVE = adverse
    (we paid up on a BUY / sold down on a SELL); NEGATIVE = price improvement.

    The side flip is the whole point: a higher fill helps a seller but hurts a buyer, so the
    same raw delta is friction for one side and improvement for the other."""
    if guideline_px <= 0:
        raise ValueError(f"guideline_px must be > 0 to reference slippage, got {guideline_px}")
    side_sign = Decimal(1) if side is Side.BUY else Decimal(-1)
    return side_sign * (fill_px - guideline_px) / guideline_px * _BPS


def fee_bps(fee_cost: Decimal, notional: Decimal) -> Decimal:
    """Realized fee as bps of notional. ``fee_cost`` is the SIGNED cost (see
    fee_cost_from_commission) so a rebate lowers friction. POSITIVE = cost."""
    if notional <= 0:
        raise ValueError(f"notional must be > 0 to reference fee bps, got {notional}")
    return fee_cost / notional * _BPS


def effective_friction_bps(guideline_px: Decimal, fill_px: Decimal, side: Side,
                           fee_cost: Decimal, size: Decimal) -> Decimal:
    """Total realized friction = adverse slippage + fee, in bps. The single number §12 asks
    per order. POSITIVE = the order cost us that many bps vs a free fill at guideline."""
    notional = fill_px * size
    return adverse_slippage_bps(guideline_px, fill_px, side) + fee_bps(fee_cost, notional)


def naive_baseline_bps(guideline_px: Decimal, touch_px: Decimal, side: Side,
                       taker_fee_bps: Decimal = TAKER_FEE_BPS) -> Decimal:
    """What a T0 naive-MARKET cross at the touch would have cost, in bps: it crosses the
    spread (guideline→touch, adverse by construction) and pays the taker fee. This is the
    per-order baseline the smart fill is measured against (§12; the 2026-07-10 audit is the
    frozen AGGREGATE baseline, this is its per-order model)."""
    return adverse_slippage_bps(guideline_px, touch_px, side) + taker_fee_bps


def savings_vs_naive_bps(effective_bps: Decimal, baseline_bps: Decimal) -> Decimal:
    """Smart-exec savings = baseline − effective. POSITIVE = we beat the naive MARKET; the
    number that makes "$91–231K" a measurement instead of a hope (§4-20)."""
    return baseline_bps - effective_bps


@dataclass(frozen=True)
class FrictionRecord:
    """One resolved order's §12 telemetry row. Every field the journal DDL carries; the
    derived bps are computed lazily so a malformed row can never poison construction."""

    request_id: str
    asset: str
    side: Side
    urgency: UrgencyClass
    maker: bool                     # True = filled as maker (post-only rested), False = taker cross
    guideline_px: Decimal          # the caller's reference price at request time
    placed_px: Decimal             # where we actually rested/sent (0 for pure MARKET)
    fill_px: Decimal               # realized average fill
    touch_px: Decimal              # the touch a naive MARKET would have crossed (baseline ref)
    size: Decimal
    fee_cost: Decimal              # SIGNED quote-currency cost (positive = paid; see fee_cost_from_commission)
    chases: int = 0                # reprice attempts spent
    queue_age_s: Decimal = Decimal(0)
    advisor_id: str = ""           # MALKHUT advice provenance ("" = none)
    triage: str = ""               # terminal disposition (filled/crossed/abandoned/…)

    @property
    def notional(self) -> Decimal:
        return self.fill_px * self.size

    def effective_bps(self) -> Decimal:
        return effective_friction_bps(self.guideline_px, self.fill_px, self.side,
                                      self.fee_cost, self.size)

    def baseline_bps(self) -> Decimal:
        return naive_baseline_bps(self.guideline_px, self.touch_px, self.side)

    def savings_bps(self) -> Decimal:
        return savings_vs_naive_bps(self.effective_bps(), self.baseline_bps())


FrictionSink = Callable[[FrictionRecord], None]


class FrictionJournal:
    """Side-lane friction telemetry (§4-5). ``record`` is fire-and-forget and CANNOT raise —
    a failing sink loses the row and logs, never disturbs the order loop (§13, b46ebd2).

    The sink is injected: in prod it writes the §12 CH rows (``exec_smart_journal``); in
    tests it's a list. The journal keeps an in-memory copy only when ``retain`` so aggregate
    queries work without a database."""

    def __init__(self, sink: FrictionSink | None = None, *, retain: bool = True,
                 logger: logging.Logger = LOGGER) -> None:
        self._sink = sink
        self._retain = retain
        self.log = logger
        self._rows: list[FrictionRecord] = []

    def record(self, rec: FrictionRecord) -> None:
        """Emit one row. Swallows ALL exceptions — telemetry never breaks execution."""
        if self._retain:
            self._rows.append(rec)
        if self._sink is None:
            return
        try:
            self._sink(rec)
        except Exception as exc:                      # noqa: BLE001 — side-lane law: never propagate
            self.log.warning("friction.record: sink failed, row dropped: %r", exc)

    def rows(self) -> list[FrictionRecord]:
        return list(self._rows)

    def friction_by_urgency(self) -> dict[UrgencyClass, Decimal]:
        """Mean effective friction bps per urgency class — the §15 rung delta. Rows whose bps
        can't be computed (bad reference px) are skipped, not fatal (side-lane)."""
        buckets: dict[UrgencyClass, list[Decimal]] = {}
        for r in self._rows:
            try:
                buckets.setdefault(r.urgency, []).append(r.effective_bps())
            except Exception:                          # noqa: BLE001
                continue
        return {u: sum(v) / len(v) for u, v in buckets.items() if v}

    def savings_by_urgency(self) -> dict[UrgencyClass, Decimal]:
        """Mean savings vs naive-MARKET per urgency — the before/after claim, per class."""
        buckets: dict[UrgencyClass, list[Decimal]] = {}
        for r in self._rows:
            try:
                buckets.setdefault(r.urgency, []).append(r.savings_bps())
            except Exception:                          # noqa: BLE001
                continue
        return {u: sum(v) / len(v) for u, v in buckets.items() if v}


# ── DDL — ships WITH the code (§12: the 404-storm lesson — tables that don't exist journal
# nothing). When this package syncs to /mnt, register EXEC_SMART_JOURNAL_DDL in the applier
# verify-set (prod/clickhouse/uv/apply_uv_ddl.py) so a missing table fails LOUD, not silent.
EXEC_SMART_JOURNAL_DDL = """\
CREATE TABLE IF NOT EXISTS {db}.exec_smart_journal (
    ts             DateTime64(3) DEFAULT now64(3),
    request_id     String,
    asset          String,
    side           Enum8('BUY' = 1, 'SELL' = 2),
    urgency        LowCardinality(String),
    maker          UInt8,
    guideline_px   Decimal(38, 12),
    placed_px      Decimal(38, 12),
    fill_px        Decimal(38, 12),
    touch_px       Decimal(38, 12),
    size           Decimal(38, 12),
    fee_cost       Decimal(38, 12),
    effective_bps  Decimal(18, 6),
    baseline_bps   Decimal(18, 6),
    savings_bps    Decimal(18, 6),
    chases         UInt16,
    queue_age_s    Decimal(18, 6),
    advisor_id     String,
    triage         LowCardinality(String)
) ENGINE = MergeTree ORDER BY (asset, ts)
"""