"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Pre-trade mandate gate for DIRECT-SDK connectors (SPEC Mandate Enforcement §3).
The MCP :class:`~src.live.order_guard.LiveOrderGuardTool` gates Robinhood by
wrapping a remote MCP tool. Direct-SDK connectors (tiger / alpaca / okx /
binance / futu) place orders through a normal Python call, not an MCP tool, so
they need a function-based gate with the SAME ceremony, all fail-closed before
any order reaches the broker:
1. ``load_mandate`` — no valid mandate / unknown schema version → DENY.
2. expiry — past ``consent.expires_at`` → DENY (routes to re-auth).
3. ``halt_flag_set`` — kill switch tripped → DENY, no broker call.
4. notional normalization — a ``quantity`` order is priced (connector quote →
data loaders) and enforced on the LARGER of explicit notional and
``quantity × price``; fail-closed DENY when unpriceable.
5. read positions + balance via the connector's own READ functions.
6. ``check_mandate`` — ALLOW → ``connector.place_order`` / DENY (structural) /
PAUSE_FOR_REAUTH (quantitative).
A daily count is consumed only on a confirmed ALLOW whose ``place_order``
returned a non-error envelope. Every decision writes one audit event and the
returned payload carries the redacted record under ``live_action``.
"""
from __future__ import annotations
import logging
from datetime import datetime, timezone
from decimal import Decimal, InvalidOperation
from typing import Any
from src.live import pending_action
from src.live.audit import LiveActionEvent, write_live_action
from src.live.daily_count import (
DailyCountError,
DailyOrderLockUnavailable,
daily_order_lock,
increment_daily_count,
read_daily_count,
)
from src.live.enforcement import (
BREACH_KIND_INSTRUMENT,
BREACH_KIND_UNIVERSE,
OrderIntent,
check_mandate,
instrument_asset_class,
last_price_usd,
)
from src.live.halt import halt_flag_set, trip_halt
from src.live.mandate.model import MANDATE_SCHEMA_VERSION, Mandate
from src.live.mandate.store import load_mandate
logger = logging.getLogger(__name__)
LIVE_ACTION_RESULT_KEY = "live_action"
_REMOTE_TOOL = "place_order"
_DECISION_ALLOW = "allow"
_DECISION_DENY = "deny"
_DECISION_PAUSE = "pause_for_reauth"
def execute_live_order(
*,
broker: str,
connector_module: Any,
config: Any,
intent: OrderIntent,
place_kwargs: dict[str, Any],
session_id: str = "",
) -> dict[str, Any]:
"""Run the live mandate gate around a direct-SDK ``place_order``.
Args:
broker: Broker key (mandate/halt/counter/audit are keyed by this).
connector_module: The connector's ``sdk`` module (provides
``place_order``/``get_positions``/``get_account_snapshot``/``get_quote``).
config: The connector config object for a LIVE profile.
intent: Normalized :class:`OrderIntent` built from the tool args.
place_kwargs: Keyword args forwarded verbatim to ``connector_module.place_order``
on ALLOW (``symbol``/``side``/``quantity``/``notional``/``order_type``/
``limit_price``/``time_in_force``).
session_id: Originating session id, stamped onto audit events.
Returns:
On ALLOW: the connector's ``place_order`` result dict (with a
``live_action`` record attached). Otherwise a refusal envelope
``{"status":"blocked","decision",...}``.
"""
broker = (broker or "").strip().lower()
mandate = load_mandate(broker)
if broker == "alpaca":
try:
with daily_order_lock(broker):
recovery = _pending_recovery_result(
broker, session_id, connector_module, config, mandate
)
except DailyOrderLockUnavailable as exc:
return _deny(
broker, session_id, str(exc),
["pending_action", "daily_order_lock"], mandate, intent=None,
)
if recovery is not None:
return recovery
if mandate is None or mandate.schema_version != MANDATE_SCHEMA_VERSION:
return _deny(broker, session_id, "no valid mandate on file", ["mandate"], mandate, intent=None)
if _is_expired(mandate):
return _deny(
broker,
session_id,
"mandate expired — re-authorize",
["mandate", "expiry"],
mandate,
intent=None,
reauth=True,
)
if halt_flag_set(broker):
return _deny(
broker, session_id, "live trading halted", ["mandate", "expiry", "halt_flag"], mandate, intent=None
)
normalized = _normalize_notional(intent, connector_module, config)
if normalized is None:
return _deny(
broker,
session_id,
"quantity order notional could not be priced (fail-closed)",
["mandate", "expiry", "halt_flag", "quote"],
mandate,
intent=intent,
)
intent = normalized
positions = _safe_read(connector_module, "get_positions", config)
balance = _safe_read(connector_module, "get_account_snapshot", config)
try:
with daily_order_lock(broker):
if broker == "alpaca":
recovery = _pending_recovery_result(
broker, session_id, connector_module, config, mandate
)
if recovery is not None:
return recovery
daily_count = read_daily_count(broker)
breach = check_mandate(
mandate,
intent,
positions,
balance,
broker=broker,
remote_tool=_REMOTE_TOOL,
daily_count=daily_count,
)
if breach is None:
return _allow(
broker,
session_id,
connector_module,
config,
intent,
place_kwargs,
mandate,
positions,
)
except DailyOrderLockUnavailable as exc:
return _deny(
broker,
session_id,
str(exc),
["mandate", "expiry", "halt_flag", "daily_order_lock"],
mandate,
intent=intent,
)
reauth = breach.kind not in (BREACH_KIND_UNIVERSE, BREACH_KIND_INSTRUMENT)
return _deny_breach(broker, session_id, breach, mandate, intent, reauth)
def _pending_recovery_result(broker, session_id, connector, config, mandate):
"""Recover an existing marker under the caller-held broker lock."""
try:
unresolved = pending_action.load_pending_action(broker)
except pending_action.PendingActionError:
return _deny(
broker, session_id, "pending broker action is invalid and requires recovery",
["pending_action", "exact_broker_evidence"], mandate,
intent=None, reason_code="pending_action_invalid",
)
if unresolved is None:
return None
if unresolved.phase == "resolved_needs_revalidation":
return _deny(
broker, session_id, "recovered broker order requires policy revalidation",
["pending_action", "exact_broker_evidence"], mandate,
intent=None, reason_code="pending_action_needs_revalidation",
)
return _recover_pending_order(
broker, session_id, connector, config, mandate, unresolved
)
def execute_live_action(
*,
broker: str,
connector_module: Any,
config: Any,
remote_tool: str,
risk_reducing: bool,
intent: OrderIntent | None,
execute_fn: Any,
audit_request: dict[str, Any] | None = None,
session_id: str = "",
structural_reason: str | None = None,
) -> dict[str, Any]:
"""Run the live mandate gate around a direct-SDK write that is not ``place_order``.
Risk-reducing actions skip halt and mandate checks but are still
audit-logged. Risk-increasing actions follow the same ceremony as
:func:`execute_live_order`. The daily-count lock covers the final state
reads, broker execution, successful count increment, and audit write so two
concurrent actions cannot both consume the same last daily slot.
"""
broker = (broker or "").strip().lower()
mandate = load_mandate(broker)
if structural_reason:
return _deny(
broker,
session_id,
structural_reason,
["structural_contract"],
mandate,
intent=intent,
)
if risk_reducing:
return _execute_and_audit_live_action(
broker=broker,
session_id=session_id,
remote_tool=remote_tool,
mandate=mandate,
intent=intent,
execute_fn=execute_fn,
audit_request=audit_request,
checked=["risk_reducing"],
consume_daily_count=False,
)
if mandate is None or mandate.schema_version != MANDATE_SCHEMA_VERSION:
return _deny(
broker,
session_id,
"no valid mandate on file",
["mandate"],
mandate,
intent=intent,
)
if intent is None:
return _deny(
broker,
session_id,
"live action missing risk intent (fail-closed)",
["mandate", "intent"],
mandate,
intent=None,
)
normalized = _normalize_notional(intent, connector_module, config)
if normalized is None:
return _deny(
broker,
session_id,
"quantity order notional could not be priced (fail-closed)",
["mandate", "quote"],
mandate,
intent=intent,
)
intent = normalized
checked = [
"mandate",
"expiry",
"halt_flag",
"exclude_symbols",
"allowed_instruments",
"asset_classes",
"max_order_notional_usd",
"max_total_exposure_usd",
"max_leverage",
"max_trades_per_day",
"account_funding_usd",
"universe_floors",
]
try:
with daily_order_lock(broker):
if _is_expired(mandate):
return _deny(
broker,
session_id,
"mandate expired — re-authorize",
["mandate", "expiry"],
mandate,
intent=intent,
reauth=True,
)
if halt_flag_set(broker):
return _deny(
broker,
session_id,
"live trading halted",
["mandate", "expiry", "halt_flag"],
mandate,
intent=intent,
)
positions = _safe_read(connector_module, "get_positions", config)
balance = _safe_read(connector_module, "get_account_snapshot", config)
breach = check_mandate(
mandate,
intent,
positions,
balance,
broker=broker,
remote_tool=remote_tool,
daily_count=read_daily_count(broker),
)
if breach is not None:
reauth = breach.kind not in (
BREACH_KIND_UNIVERSE,
BREACH_KIND_INSTRUMENT,
)
return _deny_breach(
broker,
session_id,
breach,
mandate,
intent,
reauth,
)
return _execute_and_audit_live_action(
broker=broker,
session_id=session_id,
remote_tool=remote_tool,
mandate=mandate,
intent=intent,
execute_fn=execute_fn,
audit_request=audit_request,
checked=checked,
consume_daily_count=True,
)
except DailyOrderLockUnavailable as exc:
return _deny(
broker,
session_id,
str(exc),
["mandate", "expiry", "halt_flag", "daily_order_lock"],
mandate,
intent=intent,
)
def _execute_and_audit_live_action(
*,
broker: str,
session_id: str,
remote_tool: str,
mandate: Mandate | None,
intent: OrderIntent | None,
execute_fn: Any,
audit_request: dict[str, Any] | None,
checked: list[str],
consume_daily_count: bool,
) -> dict[str, Any]:
"""Execute one approved action and atomically account for its success."""
try:
result = execute_fn()
except Exception as exc: # noqa: BLE001
logger.warning("live %s raised for %s: %s", remote_tool, broker, exc)
result = {"status": "error", "error": str(exc)}
is_error = not isinstance(result, dict) or str(result.get("status", "")).lower() != "ok"
if is_error:
record = _audit_action(
broker,
session_id,
remote_tool=remote_tool,
kind="order_rejected",
outcome="error",
mandate=mandate,
intent=intent,
broker_request=audit_request,
broker_response=result if isinstance(result, dict) else {"raw": result},
gate_decision={
"allowed": True,
"decision": _DECISION_ALLOW,
"checked_limits": checked,
},
error=_error_message(result),
)
else:
if consume_daily_count:
increment_daily_count(broker)
record = _audit_action(
broker,
session_id,
remote_tool=remote_tool,
kind="order_placed",
outcome="accepted",
mandate=mandate,
intent=intent,
broker_request=audit_request,
broker_response=result,
gate_decision={
"allowed": True,
"decision": _DECISION_ALLOW,
"checked_limits": checked,
},
)
if isinstance(result, dict) and record is not None:
result = {**result, LIVE_ACTION_RESULT_KEY: record}
if isinstance(result, dict):
return result
return {"status": "error", "error": "non-dict broker result"}
# --------------------------------------------------------------------------- #
# Decision helpers
# --------------------------------------------------------------------------- #
def _allow(broker, session_id, connector_module, config, intent, place_kwargs, mandate, positions) -> dict[str, Any]:
"""Execute the order; consume a count + audit only on a non-error result."""
pending = None
if broker == "alpaca":
pre_position_qty = _pre_position_qty(positions, intent.symbol)
if place_kwargs.get("quantity") is not None and pre_position_qty is None:
return _deny(
broker, session_id, "exact pre-position evidence is unavailable",
["mandate", "expiry", "halt_flag", "pending_action", "position"],
mandate, intent=intent,
reason_code="pending_position_evidence_unavailable",
)
try:
pending = pending_action.new_pending_order(
broker, place_kwargs,
pre_position_qty=pre_position_qty,
)
pending_action.save_pending_action(pending)
except Exception as exc: # noqa: BLE001 - missing evidence forbids the write
logger.warning("pending action write failed for %s: %s", broker, exc)
return _deny(
broker, session_id, "pending broker action could not be persisted",
["mandate", "expiry", "halt_flag", "pending_action"], mandate,
intent=intent, reason_code="pending_action_persist_failed",
)
place_kwargs = {**place_kwargs, "client_order_id": pending.client_order_id}
try:
result = connector_module.place_order(config, **place_kwargs)
except Exception as exc: # noqa: BLE001 - a connector raise must not escape the gate
logger.warning("live place_order raised for %s: %s", broker, exc)
result = {"status": "error", "error": str(exc)}
is_error = not isinstance(result, dict) or str(result.get("status", "")).lower() != "ok"
accounting_failed = False
checked = [
"mandate",
"expiry",
"halt_flag",
"exclude_symbols",
"allowed_instruments",
"asset_classes",
"max_order_notional_usd",
"max_total_exposure_usd",
"max_leverage",
"max_trades_per_day",
"account_funding_usd",
"universe_floors",
]
if is_error:
record = _audit(
broker,
session_id,
kind="order_rejected",
outcome="error",
mandate=mandate,
intent=intent,
broker_request=dict(place_kwargs),
broker_response=result if isinstance(result, dict) else {"raw": result},
gate_decision={"allowed": True, "decision": _DECISION_ALLOW, "checked_limits": checked,
**({"reason_code": "pending_action_unresolved"} if pending else {})},
error=_error_message(result),
)
else:
try:
if pending is not None:
increment_daily_count(broker, pending.action_id)
else:
increment_daily_count(broker)
except DailyCountError:
accounting_failed = True
record = _audit(
broker,
session_id,
kind="order_placed",
outcome="accepted",
mandate=mandate,
intent=intent,
broker_request=dict(place_kwargs),
broker_response=result,
gate_decision={"allowed": True, "decision": _DECISION_ALLOW, "checked_limits": checked,
**({"reason_code": "daily_action_accounting_failed"} if accounting_failed else {})},
)
if isinstance(result, dict) and record is not None:
result = {**result, LIVE_ACTION_RESULT_KEY: record}
if pending is not None:
cleared = False
exact_ack = (
isinstance(result, dict)
and result.get("client_order_id") == pending.client_order_id
and bool(result.get("order_id"))
)
if not is_error and not accounting_failed and exact_ack and record is not None:
try:
pending_action.clear_pending_action(broker, pending.action_id)
cleared = True
except Exception as exc: # noqa: BLE001 - retain the recovery block
logger.warning("pending action clear failed for %s: %s", broker, exc)
if not cleared:
result = {
**(result if isinstance(result, dict) else {"status": "error"}),
"client_order_id": pending.client_order_id,
"recovery_pending": True,
"reason_code": "pending_action_unresolved",
}
return result if isinstance(result, dict) else {"status": "error", "error": "non-dict broker result"}
def _recover_pending_order(broker, session_id, connector, config, mandate, action):
"""Resolve one Alpaca submission by exact identity, never by resubmission."""
checked = ["mandate", "expiry", "halt_flag", "pending_action", "exact_broker_evidence"]
def unresolved(reason):
return _deny(
broker, session_id, reason, checked, mandate,
intent=None, reason_code="pending_action_unresolved",
)
lookup = getattr(connector, "get_order_by_client_order_id", None)
if lookup is None:
return unresolved("connector lacks exact order recovery")
try:
response = lookup(config, client_order_id=action.client_order_id)
except Exception as exc: # noqa: BLE001 - read failure is insufficient evidence
response = {"status": "error", "error": str(exc)}
evidence = _validate_recovery_evidence(action, response)
if evidence is None:
return unresolved("exact broker evidence is missing or contradictory")
status = evidence["order_status"]
filled = Decimal(str(evidence["filled_qty"]))
working = {"accepted", "new", "open", "pending_new", "accepted_for_bidding"}
terminal = {"rejected", "canceled", "expired"}
fill_statuses = {"partially_filled", "filled"}
if (filled == 0 and status in fill_statuses) or (
filled > 0 and status not in fill_statuses | {"canceled", "expired"}
):
return _halt_fill_recovery(
broker, session_id, mandate, action, evidence, None,
"broker status contradicts filled quantity", checked,
)
if status != "rejected":
try:
increment_daily_count(broker, action.action_id)
except DailyCountError:
return unresolved("recovered order could not be durably accounted")
if filled > 0:
return _recover_correlated_fill(
broker, session_id, connector, config, mandate, action, evidence, checked
)
record = _audit(
broker, session_id,
kind="order_rejected" if status == "rejected" else "order_placed",
outcome="rejected" if status == "rejected" else ("filled" if status == "filled" else "accepted"),
mandate=mandate, intent=None,
broker_request=action.request.model_dump(mode="json"), broker_response=evidence,
gate_decision={"allowed": False, "decision": _DECISION_DENY,
"checked_limits": checked, "reason_code": "exact_submit_recovered",
"action_id": action.action_id},
)
if record is None:
return _recovery_refusal(broker, "recovery audit was not durable")
if status in working:
try:
pending_action.transition_to_revalidation(action, evidence)
except Exception as exc: # noqa: BLE001 - retain the recovery block
logger.warning("pending action transition failed for %s: %s", broker, exc)
return _recovery_refusal(broker, "recovered order transition was not durable", record)
return _recovery_refusal(
broker, "recovered working order requires policy revalidation", record,
reason_code="pending_action_needs_revalidation",
)
if status in terminal:
try:
pending_action.clear_pending_action(broker, action.action_id)
except Exception as exc: # noqa: BLE001 - retain the recovery block
logger.warning("pending action clear failed for %s: %s", broker, exc)
return _recovery_refusal(broker, "terminal recovery could not be cleared", record)
return _recovery_refusal(
broker, "exact terminal broker outcome recovered", record,
reason_code="pending_action_resolved_terminal", recovery_pending=False,
)
return _recovery_refusal(broker, "exact fill requires position attribution", record)
def _recover_correlated_fill(
broker, session_id, connector, config, mandate, action, evidence, checked
):
"""Attribute an exact quantity fill to the signed broker position delta."""
request_qty = _exact_decimal(action.request.quantity)
status = evidence["order_status"]
persisted = action.position_resolution
same_resolution = (
action.phase == "resolved_fill_pending_audit"
and action.resolution is not None
and action.resolution.model_dump(mode="json") == evidence
and persisted is not None
)
if same_resolution:
positions = None
before = _exact_decimal(persisted.pre_position_qty)
after = _exact_decimal(persisted.current_position_qty)
filled = _exact_decimal(persisted.attributed_filled_qty)
else:
positions = _safe_read(connector, "get_positions", config)
before = _exact_decimal(action.pre_position_qty)
after = _exact_position_qty(positions, action.request.symbol)
filled = _exact_decimal(evidence["filled_qty"])
coherent_size = (
request_qty is not None
and filled is not None
and 0 < filled <= request_qty
and before is not None
and after is not None
and (status != "filled" or filled == request_qty)
and (status not in {"partially_filled", "canceled", "expired"} or filled < request_qty)
)
expected_after = None
if coherent_size:
expected_after = before + filled if action.request.side == "buy" else before - filled
if not coherent_size or after != expected_after:
return _halt_fill_recovery(
broker, session_id, mandate, action, evidence, positions,
"exact fill does not match durable quantity and signed position evidence",
checked,
)
position_evidence = {
"pre_position_qty": format(before, "f"),
"current_position_qty": format(after, "f"),
"attributed_filled_qty": format(filled, "f"),
}
if not same_resolution:
try:
action = pending_action.transition_to_fill_resolution(
action, evidence, position_evidence
)
except Exception as exc: # noqa: BLE001 - original marker remains fail-closed
logger.warning("fill resolution persistence failed for %s: %s", broker, exc)
return _recovery_refusal(broker, "fill resolution was not durable")
broker_response = {"order": evidence, "position_evidence": position_evidence}
record = _audit(
broker, session_id, kind="order_placed", outcome="filled", mandate=mandate,
intent=None, broker_request=action.request.model_dump(mode="json"),
broker_response=broker_response,
gate_decision={"allowed": False, "decision": _DECISION_DENY,
"checked_limits": checked + ["signed_position_delta"],
"reason_code": "exact_fill_attributed", "action_id": action.action_id},
)
if record is None:
return _recovery_refusal(broker, "fill attribution audit was not durable")
if status == "partially_filled":
try:
pending_action.transition_to_revalidation(action, evidence)
except Exception as exc: # noqa: BLE001 - retain exact evidence
logger.warning("fill recovery transition failed for %s: %s", broker, exc)
return _recovery_refusal(broker, "fill transition was not durable", record)
return _recovery_refusal(
broker, "working partial fill requires policy revalidation", record,
reason_code="pending_action_needs_revalidation",
)
try:
pending_action.clear_pending_action(broker, action.action_id)
except Exception as exc: # noqa: BLE001 - retain exact evidence
logger.warning("fill recovery clear failed for %s: %s", broker, exc)
return _recovery_refusal(broker, "resolved fill could not be cleared", record)
return _recovery_refusal(
broker, "exact terminal fill recovered", record,
reason_code="pending_action_resolved_fill", recovery_pending=False,
)
def _halt_fill_recovery(broker, session_id, mandate, action, evidence, positions, reason, checked):
try:
trip_halt(by="file", reason=reason, broker=broker)
except Exception as exc: # noqa: BLE001 - marker remains the fail-closed gate
logger.error("fill recovery could not persist broker halt for %s: %s", broker, exc)
record = _audit(
broker, session_id, kind="halt_tripped", outcome="blocked", mandate=mandate,
intent=None, broker_request=action.request.model_dump(mode="json"),
broker_response={"order": evidence, "positions": positions},
gate_decision={"allowed": False, "decision": _DECISION_DENY,
"checked_limits": checked + ["signed_position_delta"],
"reason_code": "pending_action_fill_inconsistent",
"action_id": action.action_id}, error=reason,
)
return _recovery_refusal(
broker, reason, record, reason_code="pending_action_fill_inconsistent"
)
def _exact_position_qty(positions, symbol) -> Decimal | None:
rows = positions.get("positions", positions.get("data")) if isinstance(positions, dict) else positions
if not isinstance(rows, list):
return None
target = str(symbol).strip().upper()
matches = [row for row in rows if isinstance(row, dict)
and str(row.get("symbol") or "").strip().upper() == target]
if not matches:
return Decimal(0)
if len(matches) != 1:
return None
row = matches[0]
exact_value = row.get("exact_quantity")
try:
quantity = _exact_decimal(
exact_value if exact_value is not None else row.get("quantity", row.get("qty"))
)
except InvalidOperation:
return None
if quantity is None:
return None
if (
exact_value is None
and str(row.get("side") or "").strip().lower() in {"short", "sell"}
and quantity > 0
):
quantity = -quantity
return quantity
def _validate_recovery_evidence(action, response) -> dict[str, Any] | None:
order = response.get("order") if isinstance(response, dict) and response.get("status") == "ok" else None
if (
not isinstance(order, dict)
or not isinstance(order.get("broker_order_id"), str)
or not order["broker_order_id"]
):
return None
request = action.request
expected = {"client_order_id": action.client_order_id, "symbol": request.symbol,
"side": request.side, "order_type": request.order_type,
"time_in_force": request.time_in_force}
if any(order.get(key) != value for key, value in expected.items()):
return None
try:
submitted = datetime.fromisoformat(str(order.get("submitted_at") or "").replace("Z", "+00:00"))
normalized = dict(order)
for key in ("quantity", "notional", "limit_price"):
actual, wanted = _exact_decimal(order.get(key)), _exact_decimal(getattr(request, key))
if actual != wanted:
return None
normalized[key] = format(actual, "f") if actual is not None else None
filled = _exact_decimal(order.get("filled_qty"))
except (InvalidOperation, ValueError):
return None
status = str(order.get("order_status") or "").strip().lower()
supported = {"accepted", "new", "open", "pending_new", "accepted_for_bidding",
"rejected", "canceled", "expired", "partially_filled", "filled"}
if submitted.tzinfo is None or filled is None or filled < 0 or status not in supported:
return None
normalized.update(broker_order_id=str(order["broker_order_id"]), filled_qty=format(filled, "f"),
order_status=status, submitted_at=submitted.isoformat())
return normalized
def _exact_decimal(value) -> Decimal | None:
if value is None:
return None
if isinstance(value, bool):
raise InvalidOperation
number = Decimal(str(value))
if not number.is_finite():
raise InvalidOperation
return number
def _recovery_refusal(
broker, reason, record=None, *, reason_code="pending_action_unresolved", recovery_pending=True
) -> dict[str, Any]:
result = _refusal(broker, decision=_DECISION_DENY, reason=reason, reauth=False, record=record)
result.update(reason_code=reason_code, recovery_pending=recovery_pending)
return result
def _deny(broker, session_id, reason, checked, mandate, *, intent, reauth=False, reason_code=None) -> dict[str, Any]:
"""Audit + return a refusal for a pre-check / structural DENY."""
record = _audit(
broker,
session_id,
kind="order_rejected",
outcome="blocked",
mandate=mandate,
intent=intent,
broker_request=None,
broker_response=None,
gate_decision={"allowed": False, "decision": _DECISION_DENY, "checked_limits": checked,
**({"reason_code": reason_code} if reason_code else {})},
error=reason,
)
result = _refusal(broker, decision=_DECISION_DENY, reason=reason, reauth=reauth, record=record)
if reason_code:
result["reason_code"] = reason_code
return result
def _deny_breach(broker, session_id, breach, mandate, intent, reauth) -> dict[str, Any]:
"""Audit + return a refusal for a ``check_mandate`` breach."""
decision = _DECISION_PAUSE if reauth else _DECISION_DENY
record = _audit(
broker,
session_id,
kind="breach",
outcome="blocked",
mandate=mandate,
intent=intent,
broker_request=None,
broker_response=None,
gate_decision={
"allowed": False,
"decision": decision,
"limit": breach.limit,
"kind": breach.kind,
"limit_value": breach.limit_value,
"attempted_value": breach.attempted_value,
},
error=breach.detail or f"order breaches {breach.limit}",
)
return _refusal(
broker,
decision=decision,
reason=breach.detail or f"order breaches {breach.limit}",
reauth=reauth,
breach=breach,
record=record,
)
def _refusal(broker, *, decision, reason, reauth, breach=None, record=None) -> dict[str, Any]:
payload: dict[str, Any] = {
"status": "blocked",
"decision": decision,
"reason": reason,
"broker": broker,
"requires_reauthorization": reauth,
}
if record is not None:
payload[LIVE_ACTION_RESULT_KEY] = record
if breach is not None:
payload["breach"] = {
"broker": breach.broker,
"limit": breach.limit,
"limit_value": breach.limit_value,
"attempted_value": breach.attempted_value,
"overage": breach.overage,
"kind": breach.kind,
"detail": breach.detail,
"proposed_action": {
"symbol": breach.proposed_action.symbol,
"side": breach.proposed_action.side,
"notional_usd": breach.proposed_action.notional_usd,
"quantity": breach.proposed_action.quantity,
"instrument_type": breach.proposed_action.instrument_type.value,
},
}
return payload
# --------------------------------------------------------------------------- #
# Notional normalization + reads
# --------------------------------------------------------------------------- #
def _normalize_notional(intent: OrderIntent, connector_module: Any, config: Any) -> OrderIntent | None:
"""Stamp a single authoritative ``notional_usd`` (quantity → priced).
Currency note: the connector quote is the broker's native currency (HKD for
HK, CNH for A-share). The mandate caps are USD; treating a local-currency
figure as USD OVER-states USD exposure for HKD/CNH (≈7-8x), so the caps bind
CONSERVATIVELY (over-deny, never under-deny). FX normalization is a follow-up
before HK/CN are promoted past the structural asset-class gate.
"""
if intent.quantity is None:
return intent
implied = _implied_notional(intent, connector_module, config)
if implied is None or implied != implied or implied <= 0:
return None
explicit = intent.notional_usd if intent.notional_usd is not None else 0.0
enforced = max(float(explicit), implied)
return OrderIntent(
symbol=intent.symbol,
side=intent.side,
notional_usd=enforced,
quantity=intent.quantity,
instrument_type=intent.instrument_type,
asset_class=intent.asset_class,
)
def _implied_notional(intent: OrderIntent, connector_module: Any, config: Any) -> float | None:
"""USD notional implied by ``intent.quantity``, fail-closed.
A connector whose quantities are not unit-sized (MT5 lots: 1 lot EURUSD ==
100,000 EUR) exposes ``quantity_notional_usd(config, symbol, quantity)``.
When present the hook is AUTHORITATIVE and there is deliberately NO fallback
to ``quantity x quote price`` — that product under-states a lot-sized order
by roughly the contract size, which would silently disarm every USD cap.
Absent the hook, behavior is byte-identical to the legacy path: quantity
times the connector/loader quote.
"""
sizer = getattr(connector_module, "quantity_notional_usd", None)
if sizer is not None:
try:
value = sizer(config, intent.symbol, intent.quantity)
except Exception as exc: # noqa: BLE001 - sizing failure → fail-closed
logger.warning("connector notional sizing failed for %s: %s", intent.symbol, exc)
return None
if value is None:
return None
return float(value)
price = _quote_price(intent, connector_module, config)
# A buy limit is fillable anywhere up to its limit, so the cap must be
# sized for the worse of the two (#18): pricing it at the quote alone
# would let a limit at 2x the market fill at twice the authorized amount.
# Sell limits do not create exposure, so the quote stands there.
if (
intent.side == "buy"
and intent.limit_price is not None
and price is not None
):
price = max(price, intent.limit_price)
if price is None:
return None
return intent.quantity * price
def _quote_price(intent: OrderIntent, connector_module: Any, config: Any) -> float | None:
"""Live USD price for the intent symbol: connector quote first, loaders next."""
broker_price = _connector_quote_price(connector_module, config, intent.symbol)
if broker_price is not None:
return broker_price
asset_class = intent.asset_class or instrument_asset_class(intent.instrument_type)
if asset_class is None:
return None
try:
return last_price_usd(intent.symbol, asset_class)
except Exception as exc: # noqa: BLE001 - loader failure → fail-closed
logger.warning("loader quote failed for %s: %s", intent.symbol, exc)
return None
def _connector_quote_price(connector_module: Any, config: Any, symbol: str) -> float | None:
"""Parse a positive price from the connector's ``get_quote`` envelope."""
getter = getattr(connector_module, "get_quote", None)
if getter is None:
return None
try:
result = getter(symbol, config=config)
except Exception as exc: # noqa: BLE001
logger.warning("connector quote failed for %s: %s", symbol, exc)
return None
if not isinstance(result, dict) or str(result.get("status", "")).lower() == "error":
return None
quote = result.get("quote")
if not isinstance(quote, dict):
return None
for key in ("last", "ask", "bid", "close"):
if key in quote:
try:
value = float(quote[key])
except (TypeError, ValueError):
continue
if value == value and value > 0:
return value
return None
def _safe_read(connector_module: Any, fn_name: str, config: Any) -> object:
"""Call a connector read fn, returning ``None`` on any error (fail-closed)."""
fn = getattr(connector_module, fn_name, None)
if fn is None:
return None
try:
result = fn(config)
except Exception as exc: # noqa: BLE001
logger.warning("connector read %s failed: %s", fn_name, exc)
return None
if isinstance(result, dict) and str(result.get("status", "")).lower() == "error":
return None
return result
def _pre_position_qty(positions: object, symbol: str) -> str | None:
quantity = _exact_position_qty(positions, symbol)
return format(quantity, "f") if quantity is not None else None
# --------------------------------------------------------------------------- #
# Audit + misc
# --------------------------------------------------------------------------- #
def _audit(
broker, session_id, *, kind, outcome, mandate, intent, broker_request, broker_response, gate_decision, error=None
) -> dict | None:
return _audit_action(
broker,
session_id,
remote_tool=_REMOTE_TOOL,
kind=kind,
outcome=outcome,
mandate=mandate,
intent=intent,
broker_request=broker_request,
broker_response=broker_response,
gate_decision=gate_decision,
error=error,
require_durable=broker == "alpaca",
)
def _audit_action(
broker,
session_id,
*,
remote_tool: str,
kind,
outcome,
mandate,
intent,
broker_request,
broker_response,
gate_decision,
error=None,
require_durable=False,
) -> dict | None:
consent = mandate.consent if mandate is not None else None
try:
event = LiveActionEvent(
kind=kind, # type: ignore[arg-type]
session_id=session_id,
outcome=outcome, # type: ignore[arg-type]
server=broker,
remote_tool=remote_tool,
intent_normalized=_describe_intent(intent),
mandate_snapshot_ref=consent.consent_token_sha256 if consent else None,
consent_record_ref=consent.account_ref if consent else None,
broker_request=broker_request,
broker_response=broker_response,
gate_decision=gate_decision,
error=error,
)
try:
return write_live_action(event, event_callback=None, trace_writer=None, require_durable=require_durable)
except TypeError:
return None if require_durable else write_live_action(event)
except Exception as exc: # auditing must never block a decision
logger.warning("live-action audit write failed (%s): %s", kind, exc)
return None
def _is_expired(mandate: Mandate) -> bool:
raw = mandate.consent.expires_at
try:
expires = datetime.fromisoformat(raw)
except (TypeError, ValueError):
return True
if expires.tzinfo is None:
expires = expires.replace(tzinfo=timezone.utc)
return datetime.now(timezone.utc) >= expires
def _error_message(result: object) -> str:
if isinstance(result, dict):
for key in ("error", "message", "detail"):
value = result.get(key)
if isinstance(value, str) and value:
return value
return "broker order returned an error"
def _describe_intent(intent: OrderIntent | None) -> str | None:
if intent is None:
return None
size = (
f"${intent.notional_usd:g}"
if intent.notional_usd is not None
else f"{intent.quantity:g} units"
if intent.quantity is not None
else "?"
)
return f"{intent.side} {size} {intent.symbol} ({intent.instrument_type.value})"