Celes Renata
494 lines
14 KiB
Python
494 lines
14 KiB
Python
"""Execution audit trail - records every step from recommendation to market outcome.
|
|
|
|
Writes structured audit events to the audit_events table so the full
|
|
decision chain is traceable: recommendation → risk evaluation → order
|
|
submission → broker response → fill/rejection/cancellation.
|
|
|
|
Each event captures the entity type, entity ID, event type, actor,
|
|
and a JSONB data payload with stage-specific details.
|
|
|
|
Requirements: 8.3, 11.3
|
|
Design: Section 4.9 (Broker Adapter), Section 6.1 (PostgreSQL audit_events)
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import logging
|
|
import uuid
|
|
from datetime import datetime, timezone
|
|
from typing import Any
|
|
|
|
import asyncpg
|
|
|
|
logger = logging.getLogger("audit")
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Event type constants
|
|
# ---------------------------------------------------------------------------
|
|
|
|
# Recommendation stage
|
|
AUDIT_RECOMMENDATION_GENERATED = "recommendation.generated"
|
|
AUDIT_RECOMMENDATION_SUPPRESSED = "recommendation.suppressed"
|
|
|
|
# Risk evaluation stage
|
|
AUDIT_RISK_EVALUATED = "risk.evaluated"
|
|
AUDIT_RISK_REJECTED = "risk.rejected"
|
|
|
|
# Order lifecycle
|
|
AUDIT_ORDER_SUBMITTED = "order.submitted"
|
|
AUDIT_ORDER_ACCEPTED = "order.accepted"
|
|
AUDIT_ORDER_FILLED = "order.filled"
|
|
AUDIT_ORDER_REJECTED = "order.rejected"
|
|
AUDIT_ORDER_CANCELLED = "order.cancelled"
|
|
AUDIT_ORDER_DUPLICATE = "order.duplicate_prevented"
|
|
|
|
# Position changes
|
|
AUDIT_POSITION_OPENED = "position.opened"
|
|
AUDIT_POSITION_CLOSED = "position.closed"
|
|
AUDIT_POSITION_UPDATED = "position.updated"
|
|
|
|
# Trading mode changes
|
|
AUDIT_TRADING_MODE_CHANGED = "trading.mode_changed"
|
|
|
|
# Operator approval workflow
|
|
AUDIT_APPROVAL_REQUESTED = "approval.requested"
|
|
AUDIT_APPROVAL_APPROVED = "approval.approved"
|
|
AUDIT_APPROVAL_REJECTED = "approval.rejected"
|
|
AUDIT_APPROVAL_EXPIRED = "approval.expired"
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Core audit writer
|
|
# ---------------------------------------------------------------------------
|
|
|
|
_INSERT_AUDIT_EVENT = """
|
|
INSERT INTO audit_events (id, event_type, entity_type, entity_id, actor, data, created_at)
|
|
VALUES ($1::uuid, $2, $3, $4::uuid, $5, $6::jsonb, $7)
|
|
"""
|
|
|
|
|
|
async def record_audit_event(
|
|
pool: asyncpg.Pool,
|
|
event_type: str,
|
|
entity_type: str,
|
|
entity_id: str,
|
|
data: dict[str, Any],
|
|
actor: str = "system",
|
|
timestamp: datetime | None = None,
|
|
) -> str:
|
|
"""Write a single audit event to PostgreSQL.
|
|
|
|
Returns the audit event UUID.
|
|
"""
|
|
event_id = str(uuid.uuid4())
|
|
ts = timestamp or datetime.now(timezone.utc)
|
|
|
|
try:
|
|
await pool.execute(
|
|
_INSERT_AUDIT_EVENT,
|
|
event_id,
|
|
event_type,
|
|
entity_type,
|
|
entity_id,
|
|
actor,
|
|
json.dumps(data, default=str),
|
|
ts,
|
|
)
|
|
except Exception:
|
|
logger.warning(
|
|
"Failed to write audit event %s for %s/%s",
|
|
event_type, entity_type, entity_id,
|
|
exc_info=True,
|
|
)
|
|
return ""
|
|
|
|
return event_id
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Convenience helpers for each execution stage
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
async def audit_recommendation_generated(
|
|
pool: asyncpg.Pool,
|
|
recommendation_id: str,
|
|
ticker: str,
|
|
action: str,
|
|
mode: str,
|
|
confidence: float,
|
|
evidence_count: int,
|
|
suppressed: bool = False,
|
|
) -> str:
|
|
"""Record that a recommendation was generated."""
|
|
event_type = AUDIT_RECOMMENDATION_SUPPRESSED if suppressed else AUDIT_RECOMMENDATION_GENERATED
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=event_type,
|
|
entity_type="recommendation",
|
|
entity_id=recommendation_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"action": action,
|
|
"mode": mode,
|
|
"confidence": confidence,
|
|
"evidence_count": evidence_count,
|
|
"suppressed": suppressed,
|
|
},
|
|
actor="recommendation_worker",
|
|
)
|
|
|
|
|
|
async def audit_risk_evaluated(
|
|
pool: asyncpg.Pool,
|
|
evaluation_id: str,
|
|
recommendation_id: str | None,
|
|
ticker: str,
|
|
eligible: bool,
|
|
allowed_mode: str,
|
|
rejection_reasons: list[str],
|
|
check_count: int,
|
|
) -> str:
|
|
"""Record a risk evaluation result."""
|
|
event_type = AUDIT_RISK_REJECTED if not eligible else AUDIT_RISK_EVALUATED
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=event_type,
|
|
entity_type="risk_evaluation",
|
|
entity_id=evaluation_id,
|
|
data={
|
|
"recommendation_id": recommendation_id,
|
|
"ticker": ticker,
|
|
"eligible": eligible,
|
|
"allowed_mode": allowed_mode,
|
|
"rejection_reasons": rejection_reasons,
|
|
"check_count": check_count,
|
|
},
|
|
actor="risk_engine",
|
|
)
|
|
|
|
|
|
async def audit_order_submitted(
|
|
pool: asyncpg.Pool,
|
|
order_id: str,
|
|
ticker: str,
|
|
side: str,
|
|
quantity: float,
|
|
order_type: str,
|
|
idempotency_key: str,
|
|
recommendation_id: str | None = None,
|
|
evaluation_id: str | None = None,
|
|
) -> str:
|
|
"""Record that an order was submitted to the broker."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_ORDER_SUBMITTED,
|
|
entity_type="order",
|
|
entity_id=order_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"side": side,
|
|
"quantity": quantity,
|
|
"order_type": order_type,
|
|
"idempotency_key": idempotency_key,
|
|
"recommendation_id": recommendation_id,
|
|
"evaluation_id": evaluation_id,
|
|
},
|
|
actor="broker_service",
|
|
)
|
|
|
|
|
|
async def audit_order_filled(
|
|
pool: asyncpg.Pool,
|
|
order_id: str,
|
|
ticker: str,
|
|
side: str,
|
|
fill_quantity: float,
|
|
fill_price: float | None,
|
|
broker_order_id: str,
|
|
) -> str:
|
|
"""Record that an order was filled by the broker."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_ORDER_FILLED,
|
|
entity_type="order",
|
|
entity_id=order_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"side": side,
|
|
"fill_quantity": fill_quantity,
|
|
"fill_price": fill_price,
|
|
"broker_order_id": broker_order_id,
|
|
},
|
|
actor="broker_service",
|
|
)
|
|
|
|
|
|
async def audit_order_rejected(
|
|
pool: asyncpg.Pool,
|
|
order_id: str,
|
|
ticker: str,
|
|
reason: str,
|
|
source: str = "broker",
|
|
) -> str:
|
|
"""Record that an order was rejected (by risk engine or broker)."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_ORDER_REJECTED,
|
|
entity_type="order",
|
|
entity_id=order_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"reason": reason,
|
|
"rejection_source": source,
|
|
},
|
|
actor="broker_service",
|
|
)
|
|
|
|
|
|
async def audit_order_cancelled(
|
|
pool: asyncpg.Pool,
|
|
order_id: str,
|
|
ticker: str,
|
|
broker_order_id: str,
|
|
) -> str:
|
|
"""Record that an order was cancelled."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_ORDER_CANCELLED,
|
|
entity_type="order",
|
|
entity_id=order_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"broker_order_id": broker_order_id,
|
|
},
|
|
actor="broker_service",
|
|
)
|
|
|
|
|
|
async def audit_duplicate_prevented(
|
|
pool: asyncpg.Pool,
|
|
order_id: str,
|
|
ticker: str,
|
|
idempotency_key: str,
|
|
detected_via: str,
|
|
) -> str:
|
|
"""Record that a duplicate order was prevented."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_ORDER_DUPLICATE,
|
|
entity_type="order",
|
|
entity_id=order_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"idempotency_key": idempotency_key,
|
|
"detected_via": detected_via,
|
|
},
|
|
actor="broker_service",
|
|
)
|
|
|
|
|
|
async def audit_position_change(
|
|
pool: asyncpg.Pool,
|
|
order_id: str,
|
|
ticker: str,
|
|
side: str,
|
|
quantity_before: float,
|
|
quantity_after: float,
|
|
avg_entry_before: float,
|
|
avg_entry_after: float,
|
|
) -> str:
|
|
"""Record a position change resulting from a fill."""
|
|
if quantity_before == 0 and quantity_after > 0:
|
|
event_type = AUDIT_POSITION_OPENED
|
|
elif quantity_after == 0:
|
|
event_type = AUDIT_POSITION_CLOSED
|
|
else:
|
|
event_type = AUDIT_POSITION_UPDATED
|
|
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=event_type,
|
|
entity_type="position",
|
|
entity_id=order_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"side": side,
|
|
"quantity_before": quantity_before,
|
|
"quantity_after": quantity_after,
|
|
"avg_entry_before": avg_entry_before,
|
|
"avg_entry_after": avg_entry_after,
|
|
},
|
|
actor="broker_service",
|
|
)
|
|
|
|
|
|
async def audit_approval_requested(
|
|
pool: asyncpg.Pool,
|
|
approval_id: str,
|
|
ticker: str,
|
|
side: str,
|
|
quantity: float,
|
|
estimated_value: float,
|
|
recommendation_id: str | None = None,
|
|
expires_at: str | None = None,
|
|
) -> str:
|
|
"""Record that an operator approval was requested for a live order."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_APPROVAL_REQUESTED,
|
|
entity_type="approval",
|
|
entity_id=approval_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"side": side,
|
|
"quantity": quantity,
|
|
"estimated_value": estimated_value,
|
|
"recommendation_id": recommendation_id,
|
|
"expires_at": expires_at,
|
|
},
|
|
actor="broker_service",
|
|
)
|
|
|
|
|
|
async def audit_approval_reviewed(
|
|
pool: asyncpg.Pool,
|
|
approval_id: str,
|
|
ticker: str,
|
|
approved: bool,
|
|
reviewed_by: str = "operator",
|
|
review_note: str = "",
|
|
) -> str:
|
|
"""Record that an operator reviewed an approval request."""
|
|
event_type = AUDIT_APPROVAL_APPROVED if approved else AUDIT_APPROVAL_REJECTED
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=event_type,
|
|
entity_type="approval",
|
|
entity_id=approval_id,
|
|
data={
|
|
"ticker": ticker,
|
|
"approved": approved,
|
|
"reviewed_by": reviewed_by,
|
|
"review_note": review_note,
|
|
},
|
|
actor=reviewed_by,
|
|
)
|
|
|
|
|
|
async def audit_approval_expired(
|
|
pool: asyncpg.Pool,
|
|
approval_id: str,
|
|
ticker: str,
|
|
) -> str:
|
|
"""Record that an approval request expired without review."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_APPROVAL_EXPIRED,
|
|
entity_type="approval",
|
|
entity_id=approval_id,
|
|
data={"ticker": ticker},
|
|
actor="system",
|
|
)
|
|
|
|
|
|
async def audit_trading_mode_changed(
|
|
pool: asyncpg.Pool,
|
|
config_id: str,
|
|
old_mode: str,
|
|
new_mode: str,
|
|
actor: str = "operator",
|
|
) -> str:
|
|
"""Record a trading mode change."""
|
|
return await record_audit_event(
|
|
pool,
|
|
event_type=AUDIT_TRADING_MODE_CHANGED,
|
|
entity_type="risk_config",
|
|
entity_id=config_id,
|
|
data={
|
|
"old_mode": old_mode,
|
|
"new_mode": new_mode,
|
|
},
|
|
actor=actor,
|
|
)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Query helpers for audit trail retrieval (Requirement 11.3)
|
|
# ---------------------------------------------------------------------------
|
|
|
|
_FETCH_AUDIT_TRAIL_FOR_ORDER = """
|
|
SELECT id, event_type, entity_type, entity_id, actor, data, created_at
|
|
FROM audit_events
|
|
WHERE entity_id = $1::uuid
|
|
OR data->>'recommendation_id' = $2
|
|
OR data->>'order_id' = $2
|
|
ORDER BY created_at ASC
|
|
"""
|
|
|
|
_FETCH_AUDIT_TRAIL_BY_ENTITY = """
|
|
SELECT id, event_type, entity_type, entity_id, actor, data, created_at
|
|
FROM audit_events
|
|
WHERE entity_type = $1 AND entity_id = $2::uuid
|
|
ORDER BY created_at ASC
|
|
"""
|
|
|
|
_FETCH_FULL_EXECUTION_TRAIL = """
|
|
SELECT id, event_type, entity_type, entity_id, actor, data, created_at
|
|
FROM audit_events
|
|
WHERE entity_id = $1::uuid
|
|
OR entity_id IN (
|
|
SELECT entity_id FROM audit_events
|
|
WHERE data->>'recommendation_id' = $2
|
|
)
|
|
ORDER BY created_at ASC
|
|
"""
|
|
|
|
|
|
async def get_order_audit_trail(
|
|
pool: asyncpg.Pool,
|
|
order_id: str,
|
|
recommendation_id: str | None = None,
|
|
) -> list[dict[str, Any]]:
|
|
"""Fetch the full audit trail for an order, including related recommendation and risk events.
|
|
|
|
Returns events ordered chronologically so the full decision chain
|
|
is visible: recommendation → risk → order → fill/reject.
|
|
"""
|
|
ref_id = recommendation_id or order_id
|
|
rows = await pool.fetch(_FETCH_AUDIT_TRAIL_FOR_ORDER, order_id, ref_id)
|
|
return [
|
|
{
|
|
"id": str(row["id"]),
|
|
"event_type": row["event_type"],
|
|
"entity_type": row["entity_type"],
|
|
"entity_id": str(row["entity_id"]),
|
|
"actor": row["actor"],
|
|
"data": row["data"] if isinstance(row["data"], dict) else json.loads(row["data"]),
|
|
"created_at": row["created_at"].isoformat() if row["created_at"] else None,
|
|
}
|
|
for row in rows
|
|
]
|
|
|
|
|
|
async def get_entity_audit_trail(
|
|
pool: asyncpg.Pool,
|
|
entity_type: str,
|
|
entity_id: str,
|
|
) -> list[dict[str, Any]]:
|
|
"""Fetch all audit events for a specific entity."""
|
|
rows = await pool.fetch(_FETCH_AUDIT_TRAIL_BY_ENTITY, entity_type, entity_id)
|
|
return [
|
|
{
|
|
"id": str(row["id"]),
|
|
"event_type": row["event_type"],
|
|
"entity_type": row["entity_type"],
|
|
"entity_id": str(row["entity_id"]),
|
|
"actor": row["actor"],
|
|
"data": row["data"] if isinstance(row["data"], dict) else json.loads(row["data"]),
|
|
"created_at": row["created_at"].isoformat() if row["created_at"] else None,
|
|
}
|
|
for row in rows
|
|
]
|