@senpi/runtime 3.0.9-dev.feat-strategy-compos.20260722213012 → 3.0.9-dev.feat-strategy-compos.20260723050017

package/dist/composer/verbs/ledger.py

@@ -0,0 +1,453 @@
+"""ledger — the account MONEY-FLOW view for ``composer ledger`` (slice K6).
+
+``composer status`` (bare, J2) is the lifecycle/PROTECTION portfolio view; ``composer review`` (J8)
+is trade-QUALITY analysis. "Walk me through every dollar" / "how much have I funded vs withdrawn" is
+a THIRD, distinct question — the account MONEY-FLOW ledger — and it gets its own verb so neither of
+those surfaces has to answer a question it was not built for.
+
+WHY A DEDICATED VERB (not a status section): the confabulation this slice kills (dev-test #7, F4) was
+the model HAND-DERIVING a per-dollar PnL table because NO money-flow render existed — so it invented
+rows that corresponded to no tool output. The fix is a single-producer render the skill QUOTES
+VERBATIM. status is already dense (stage/wallet/runtime/protection + stranded + manual per strategy);
+bolting a money table onto it blurs both. review homes realized-PnL but on the trade-quality axis, not
+capital in/out. So ledger is its own thin verb.
+
+It composes ONLY existing fields — nothing is derived that the backend does not already carry:
+
+  * per-strategy ``totalFunded`` / ``totalWithdrawn`` / ``netFunded`` — from MCP ``strategy_list``
+    (source named ``backend strategy_list``). ``net`` prefers the explicit ``netFunded`` field; when
+    the backend carries none it is COMPUTED as ``funded − withdrawn`` (only when BOTH are present) and
+    labeled computed. A field the backend did not return renders "unavailable (reason)" — NEVER zero.
+  * per-strategy realized PnL — summed from the backend closed-trade ledger via
+    ``discovery_get_trader_history`` (the SAME seam ``composer review`` reads; source named
+    ``backend trade history``). A per-wallet history transport failure degrades THAT strategy's PnL
+    cell only, never the whole ledger.
+  * the free embedded-wallet balance — from MCP ``account_get_portfolio`` (source named
+    ``backend account_get_portfolio``), reusing ``fund``'s exact free-USDC definition (Hyperliquid +
+    EVM), so ledger and the fund preflight agree on what "free balance" means.
+
+FAIL-LOUD honesty (settled doctrine): every unavailable input renders "unavailable (reason)"; every
+quoted figure NAMES its source; a missing MCP credential is the teaching CMP223 (like ``fund``/
+``close``); a ``strategy_list`` transport failure is CMP260 (the account-wide enumeration cannot be
+built) while a single strategy's history failure degrades only that row.
+
+SCOPE is ACCOUNT-LEVEL: ledger enumerates ALL live strategies from ``strategy_list`` (money flow is an
+account question, not a composer-inventory one) and, when a state root is available, JOINS the
+composer-known strategy NAME onto a row by wallet. The state root is therefore OPTIONAL — a bare run
+labels rows by their backend ``strategyName``.
+
+The single MCP touch point is the injectable ``mcp_fn`` seam (see ``_box``), so the whole verb is
+tested with no network — a stubbed ``mcp_fn`` dispatches on the tool name.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from composer.validator.errors import Location, TeachingError
+
+from . import _box
+from ._box import LIVE_STATUSES, McpCredsMissing, McpError, McpFn
+from ._layout import resolve_wallet_json
+from .close import (
+    _dig,
+    _find_list,
+    _strat_id,
+    _strat_name,
+    _strat_status,
+    _strat_wallet,
+    _strategy_obj,
+)
+from .fund import _available_usd, _rec_wallet
+from .portfolio import enumerate_strategies
+from .review import HistoryUnavailable, _parse_closed_trades, default_closed_history
+
+# The named sources every figure is attributed to (printed so an operator always knows the producer).
+SRC_FUNDING = "backend strategy_list"          # totalFunded / totalWithdrawn / netFunded per strategy
+SRC_HISTORY = "backend trade history"          # discovery_get_trader_history (onchain closed ledger)
+SRC_BALANCE = "backend account_get_portfolio"  # free embedded-wallet USDC (Hyperliquid + EVM)
+
+
+# --------------------------------------------------------------------------- helpers
+
+def _num(v) -> Optional[float]:
+    """A tolerant number read (the gateway stringifies some decimals)."""
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    if isinstance(v, str):
+        try:
+            return float(v.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _money(v: float) -> str:
+    return f"-${abs(v):,.2f}" if v < 0 else f"${v:,.2f}"
+
+
+def _wallet_label(w: str) -> str:
+    """The truncated 0x… form (mirrors close.py's target/wallet labels); full address rides in
+    --json. A short/empty wallet renders plainly rather than a misleading ellipsis."""
+    return (w[:14] + "…") if w and len(w) > 15 else (w or "unknown")
+
+
+# --------------------------------------------------------------------------- one money figure
+
+@dataclass
+class Cell:
+    """One money figure with its availability. FAIL-LOUD: an unavailable figure carries the REASON
+    and is NEVER silently zeroed; a computed value (net = funded − withdrawn) is flagged."""
+
+    available: bool
+    value: Optional[float] = None
+    reason: str = ""
+    computed: bool = False
+
+    @classmethod
+    def ok(cls, value: float, *, computed: bool = False) -> "Cell":
+        return cls(True, float(value), "", computed)
+
+    @classmethod
+    def na(cls, reason: str) -> "Cell":
+        return cls(False, None, reason, False)
+
+    def to_json(self) -> dict:
+        out: dict = {"available": self.available, "value": self.value, "reason": self.reason}
+        if self.computed:
+            out["computed"] = True
+        return out
+
+    def cell_str(self, *, mark_computed: bool = False) -> str:
+        if not self.available:
+            return "unavailable"
+        s = _money(self.value if self.value is not None else 0.0)
+        return s + "*" if (mark_computed and self.computed) else s
+
+
+def _money_cell(obj: dict, label: str, *keys: str) -> Cell:
+    """Read a money field from a ``strategy_list`` record. An ABSENT key is LOUD-unavailable (never
+    0); a present-but-non-numeric value is LOUD-unavailable naming the offending value."""
+    v = _dig(obj, *keys)
+    if v is None:
+        return Cell.na(f"{SRC_FUNDING} carried no {label} field for this strategy")
+    n = _num(v)
+    if n is None:
+        return Cell.na(f"{SRC_FUNDING} carried {label} as a non-number ({v!r})")
+    return Cell.ok(n)
+
+
+def _derive_net(funded: Cell, withdrawn: Cell, obj: dict) -> Cell:
+    """``net`` prefers the explicit backend ``netFunded`` field; falls back to a COMPUTED
+    ``funded − withdrawn`` only when BOTH are present; otherwise LOUD-unavailable naming which input
+    was missing (never a guessed 0)."""
+    v = _dig(obj, "netFunded", "net_funded", "netDeposited")
+    if v is not None:
+        n = _num(v)
+        if n is not None:
+            return Cell.ok(n)
+    if funded.available and withdrawn.available:
+        return Cell.ok(funded.value - withdrawn.value, computed=True)
+    missing = [name for name, cell in (("funded", funded), ("withdrawn", withdrawn))
+               if not cell.available]
+    return Cell.na(f"{SRC_FUNDING} carried no netFunded field and net cannot be computed "
+                   f"({' & '.join(missing)} unavailable)")
+
+
+def _realized_cell(wallet: str, mcp_fn: McpFn) -> Cell:
+    """Realized PnL for one wallet = sum of the backend closed-trade ledger's realized PnL (via
+    ``discovery_get_trader_history`` — review.py's exact seam + parse). A transport/credential
+    failure for THIS wallet degrades to LOUD-unavailable (the sweep survives), never a fake 0."""
+    if not wallet:
+        return Cell.na("no wallet on this strategy record — cannot read trade history")
+    try:
+        rows = default_closed_history(wallet, mcp_fn)
+    except HistoryUnavailable as e:
+        return Cell.na(str(e))
+    except Exception as e:  # noqa: BLE001 — a surprise seam fault is a per-strategy datum, not a crash
+        return Cell.na(f"trade history read raised ({e})")
+    trades = _parse_closed_trades(rows)
+    total = round(sum(_num(t.get("realized_pnl")) or 0.0 for t in trades), 2)
+    return Cell.ok(total)
+
+
+def _balance_cell(mcp_fn: McpFn) -> Cell:
+    """The free embedded-wallet balance via ``account_get_portfolio`` — reusing ``fund._available_usd``
+    (free Hyperliquid + EVM USDC) so ledger and the fund preflight define "free balance" identically.
+    A creds/transport/unreadable-shape failure degrades LOUD, never a fabricated 0."""
+    try:
+        raw = mcp_fn("account_get_portfolio", timeout=_box._SUBMIT_TIMEOUT)
+    except McpCredsMissing as e:
+        return Cell.na(f"MCP credentials missing ({e})")
+    except McpError as e:
+        return Cell.na(f"MCP error reading account portfolio ({e})")
+    except Exception as e:  # noqa: BLE001
+        return Cell.na(f"could not read account portfolio ({e})")
+    v = _available_usd(raw)
+    if v is None:
+        return Cell.na("account_get_portfolio returned no readable free-USDC balance")
+    return Cell.ok(v)
+
+
+def _composer_names_by_wallet(base_state_dir: str) -> dict:
+    """Map lower-cased wallet address → composer strategy NAME for every accountable strategy under
+    the state root (best-effort; a malformed/absent record is skipped). Used to LABEL a backend row
+    with its composer name when we know it — money flow stays account-level, names are a courtesy."""
+    out: dict = {}
+    try:
+        names = enumerate_strategies(Path(base_state_dir))
+    except Exception:  # noqa: BLE001 — an unreadable state root just means no name join
+        return out
+    for strat in names:
+        wj_path, _layout = resolve_wallet_json(base_state_dir, strat)
+        if wj_path is None:
+            continue
+        try:
+            rec = json.loads(wj_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        w = _rec_wallet(rec)
+        if w:
+            out[w.lower()] = strat
+    return out
+
+
+# --------------------------------------------------------------------------- per-strategy row
+
+@dataclass
+class LedgerStrategy:
+    name: str                 # composer-known name if joined, else the backend strategyName / wallet
+    backend_name: str
+    wallet: str
+    strategy_id: Optional[str]
+    status: str
+    funded: Cell
+    withdrawn: Cell
+    net: Cell
+    realized: Cell
+
+    def to_json(self) -> dict:
+        return {
+            "strategy": self.name,
+            "backend_name": self.backend_name,
+            "wallet": self.wallet,
+            "strategy_id": self.strategy_id,
+            "status": self.status,
+            "funded": self.funded.to_json(),
+            "withdrawn": self.withdrawn.to_json(),
+            "net": self.net.to_json(),
+            "realized_pnl": self.realized.to_json(),
+        }
+
+
+# --------------------------------------------------------------------------- result
+
+@dataclass
+class LedgerResult:
+    base_state_dir: Optional[str]
+    strategies: list = field(default_factory=list)
+    balance: Cell = field(default_factory=lambda: Cell.na("not read"))
+    error: Optional[TeachingError] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    def _total(self, attr: str) -> tuple[float, bool]:
+        """Sum the AVAILABLE values for one column; the total is a FLOOR (partial=True) when any
+        row's value was unavailable (never silently counted as 0)."""
+        cells = [getattr(s, attr) for s in self.strategies]
+        vals = [c.value for c in cells if c.available and c.value is not None]
+        partial = any(not c.available for c in cells)
+        return round(sum(vals), 2), partial
+
+    def to_json(self) -> dict:
+        fv, fp = self._total("funded")
+        wv, wp = self._total("withdrawn")
+        nv, npart = self._total("net")
+        rv, rp = self._total("realized")
+        return {
+            "verb": "ledger",
+            "state_dir": self.base_state_dir,
+            "sources": {"funding": SRC_FUNDING, "realized_pnl": SRC_HISTORY, "balance": SRC_BALANCE},
+            "ok": self.ok,
+            "strategy_count": len(self.strategies),
+            "strategies": [s.to_json() for s in self.strategies],
+            "embedded_wallet_balance": self.balance.to_json(),
+            "totals": {
+                "funded": {"value": fv, "partial": fp},
+                "withdrawn": {"value": wv, "partial": wp},
+                "net": {"value": nv, "partial": npart},
+                "realized_pnl": {"value": rv, "partial": rp},
+            },
+            "error_count": 1 if self.error else 0,
+            "errors": [self.error.to_dict()] if self.error else [],
+        }
+
+    def render(self) -> str:
+        if self.error is not None:
+            return self.error.render() + "\n"
+
+        state_note = (f"  (state: {self.base_state_dir})" if self.base_state_dir
+                      else "  (no state root — rows labeled by backend name)")
+        lines = [
+            f"ledger — account money-flow{state_note}",
+            f"funded / withdrawn / net: {SRC_FUNDING} · realized PnL: {SRC_HISTORY} · "
+            f"embedded-wallet balance: {SRC_BALANCE}.",
+            "every figure is quoted from a NAMED backend source; unavailable inputs read "
+            "\"unavailable\" (see notes), never assumed zero.",
+            "",
+            f"strategies ({len(self.strategies)}):",
+        ]
+
+        header = ("strategy", "wallet", "funded", "withdrawn", "net", "realized PnL")
+        if not self.strategies:
+            lines.append("  (none — no live strategies on this account per backend strategy_list)")
+        else:
+            rows = [(
+                s.name,
+                _wallet_label(s.wallet),
+                s.funded.cell_str(),
+                s.withdrawn.cell_str(),
+                s.net.cell_str(mark_computed=True),
+                s.realized.cell_str(),
+            ) for s in self.strategies]
+
+            fv, fp = self._total("funded")
+            wv, wp = self._total("withdrawn")
+            nv, npart = self._total("net")
+            rv, rp = self._total("realized")
+            total_row = ("TOTAL", "", _money(fv), _money(wv), _money(nv), _money(rv))
+
+            all_rows = [header] + rows + [total_row]
+            widths = [max(len(r[i]) for r in all_rows) for i in range(6)]
+
+            def _fmt(r: tuple) -> str:
+                cells = [
+                    (r[i].ljust(widths[i]) if i < 2 else r[i].rjust(widths[i]))
+                    for i in range(6)
+                ]
+                return "  " + "  ".join(cells).rstrip()
+
+            sep = "  " + "-" * (sum(widths) + 2 * (len(widths) - 1))
+            lines.append(_fmt(header))
+            lines.append(sep)
+            lines.extend(_fmt(r) for r in rows)
+            lines.append(sep)
+            lines.append(_fmt(total_row))
+
+        # embedded-wallet balance — the free capital NOT deployed into any strategy.
+        lines.append("")
+        if self.balance.available:
+            lines.append(f"embedded-wallet balance (free, not deployed): "
+                         f"{_money(self.balance.value)}  [{SRC_BALANCE}]")
+        else:
+            lines.append(f"embedded-wallet balance: unavailable ({self.balance.reason})  "
+                         f"[{SRC_BALANCE}]")
+
+        # NOTES — every unavailable cell named with its reason + source; computed-net legend; FLOOR
+        # note when a total omitted an unavailable row. NOTHING is silently dropped.
+        notes: list[str] = []
+        for s in self.strategies:
+            for label, cell in (("funded", s.funded), ("withdrawn", s.withdrawn),
+                                ("net", s.net), ("realized PnL", s.realized)):
+                if not cell.available:
+                    notes.append(f"  - {s.name} {label}: unavailable — {cell.reason}")
+        if any(s.net.computed for s in self.strategies):
+            notes.append("  * net computed as funded − withdrawn (backend carried no netFunded field)")
+        if self.strategies:
+            partial_cols = [name for name, (_v, p) in (
+                ("funded", self._total("funded")), ("withdrawn", self._total("withdrawn")),
+                ("net", self._total("net")), ("realized PnL", self._total("realized")),
+            ) if p]
+            if partial_cols:
+                notes.append(f"  † TOTAL is a FLOOR — some rows' {', '.join(partial_cols)} were "
+                             f"unavailable and are excluded from the sum (never counted as zero).")
+        if notes:
+            lines.append("")
+            lines.append("notes:")
+            lines.extend(notes)
+
+        return "\n".join(lines) + "\n"
+
+
+# --------------------------------------------------------------------------- teaching errors
+
+def _creds_error(exc: Exception) -> TeachingError:
+    return TeachingError(
+        "CMP223", f"MCP credentials missing: {exc}",
+        "Set SENPI_AUTH_TOKEN or SENPI_API_KEY (and optionally SENPI_MCP_URL) — ledger reads the "
+        "money flow from the MCP server (strategy_list funding fields, account_get_portfolio "
+        "balance, and per-wallet trade history).",
+        Location(),
+    )
+
+
+def _list_error(exc: Exception) -> TeachingError:
+    return TeachingError(
+        "CMP260", f"MCP `strategy_list` failed: {str(exc)[:200]} — the money-flow ledger cannot be "
+                  f"built without it.",
+        "strategy_list is the source of every funded / withdrawn / net figure and the row set "
+        "itself. Check MCP creds/connectivity and re-run `composer ledger`. (A single strategy's "
+        "trade-history read failing degrades only that row; this is the account-wide enumeration "
+        "failing.)",
+        Location(),
+    )
+
+
+# --------------------------------------------------------------------------- entry point
+
+def run_ledger(
+    base_state_dir: Optional[str] = None,
+    *,
+    mcp_fn: McpFn = _box.default_mcp_call,
+) -> LedgerResult:
+    """The account money-flow ledger (see module docstring). Enumerates ALL live strategies from
+    ``strategy_list``, joins composer-known names by wallet when a state root is given, reads each
+    wallet's realized PnL from the backend trade history, and appends the free embedded-wallet
+    balance. Every input is fail-loud; a per-wallet history failure degrades that row only."""
+    result = LedgerResult(base_state_dir=str(base_state_dir) if base_state_dir else None)
+
+    # (1) strategy_list — the funding-ledger source AND the row set. Creds/transport are LOUD: the
+    # account-wide money flow cannot be enumerated without it (per-row history failures are separate).
+    try:
+        raw = mcp_fn("strategy_list", status=LIVE_STATUSES)
+    except McpCredsMissing as e:
+        result.error = _creds_error(e)
+        return result
+    except McpError as e:
+        result.error = _list_error(e)
+        return result
+    except Exception as e:  # noqa: BLE001 — a surprise transport fault is still the enumeration failing
+        result.error = _list_error(e)
+        return result
+
+    strategies_raw = _find_list(raw, "strategies")
+    names_by_wallet = _composer_names_by_wallet(base_state_dir) if base_state_dir else {}
+
+    for s in strategies_raw:
+        obj = _strategy_obj(s)
+        wallet = str(_strat_wallet(s) or "")
+        backend_name = str(_strat_name(s) or "")
+        composer_name = names_by_wallet.get(wallet.lower(), "")
+        name = composer_name or backend_name or (_wallet_label(wallet) if wallet else "unknown")
+
+        funded = _money_cell(obj, "totalFunded", "totalFunded", "total_funded", "funding")
+        withdrawn = _money_cell(obj, "totalWithdrawn", "totalWithdrawn", "total_withdrawn")
+        net = _derive_net(funded, withdrawn, obj)
+        realized = _realized_cell(wallet, mcp_fn)
+
+        result.strategies.append(LedgerStrategy(
+            name=name, backend_name=backend_name, wallet=wallet,
+            strategy_id=_strat_id(s), status=str(_strat_status(s) or ""),
+            funded=funded, withdrawn=withdrawn, net=net, realized=realized,
+        ))
+
+    # (2) the free embedded-wallet balance — LOUD-degrades, never a hard stop on the whole ledger.
+    result.balance = _balance_cell(mcp_fn)
+    return result