tradingSystem/app/core/etf_contract/signals.py

267 lines
14 KiB
Python

"""Pure, versioned event lifecycle for completed ETF 15-minute windows.
BUY/SELL describe price-volume pressure, never an order to trade. Redis key
retention is deliberately independent of the business lease on each event.
"""
from __future__ import annotations
from copy import deepcopy
from datetime import datetime, timedelta
import hashlib
import json
from zoneinfo import ZoneInfo
from .timing import LEGACY_POLICY, admission_until, lease_until, policy_version
SHANGHAI = ZoneInfo("Asia/Shanghai")
SCOPES = ("WINDOW_15M", "SESSION_CUM")
LEASE = timedelta(minutes=20)
KNOWN_DIRECTIONS = frozenset({"BUY", "SELL", "MIXED"})
DIRECTIONS = KNOWN_DIRECTIONS | {"UNKNOWN"}
def aware_time(value) -> datetime:
if isinstance(value, str):
value = datetime.fromisoformat(value.replace("Z", "+00:00"))
if not isinstance(value, datetime) or value.tzinfo is None or value.utcoffset() is None:
raise ValueError("timestamps must be timezone-aware")
return value.astimezone(SHANGHAI)
def iso(value) -> str:
return aware_time(value).isoformat()
def validate_snapshot(snapshot: dict) -> datetime:
for key in ("round_id", "trade_date", "model_version", "subjects"):
if key not in snapshot:
raise ValueError("snapshot missing " + key)
for key in ("round_id", "trade_date", "model_version"):
if not isinstance(snapshot[key], str) or not snapshot[key]:
raise ValueError(key + " must be a nonempty string")
if snapshot.get("schema_version", 1) != 1:
raise ValueError("unsupported schema_version")
end = aware_time(snapshot["window_end"])
if end.date().isoformat() != snapshot["trade_date"]:
raise ValueError("trade_date must match window_end in Asia/Shanghai")
minute = end.hour * 60 + end.minute
if (end.second or end.microsecond or end.minute % 15
or not (585 <= minute <= 690 or 795 <= minute <= 900)):
raise ValueError("window_end must be a completed regular 15-minute trading slot")
if snapshot.get("mode", "LIVE") not in ("LIVE", "REPLAY"):
raise ValueError("mode must be LIVE or REPLAY")
if type(snapshot.get("revision", 0)) is not int or snapshot.get("revision", 0) < 0:
raise ValueError("revision must be a nonnegative integer")
if not isinstance(snapshot["subjects"], list):
raise ValueError("subjects must be a list")
policy_version(snapshot)
return end
def _subject_key(subject, scope):
return json.dumps([subject["subject_type"], subject["subject_id"], scope], separators=(",", ":"))
def _event_id(snapshot, subject, scope, direction):
identity = [snapshot["model_version"], snapshot["trade_date"],
subject["subject_type"], subject["subject_id"], scope,
iso(snapshot["window_end"]), direction]
# Preserve historical identifiers, while a new timing contract cannot
# reuse an old event identity even in a revision of the same window.
if policy_version(snapshot) != LEGACY_POLICY:
identity.append(policy_version(snapshot))
if snapshot.get("publication_mode") == "observation":
identity.extend(("observation", snapshot["release_id"]))
return "etf_" + hashlib.sha256(json.dumps(identity, separators=(",", ":")).encode()).hexdigest()[:24]
def _last_known_direction(active):
"""Read new and previously persisted states without inventing a direction."""
known = active.get("last_known_direction")
if isinstance(known, str) and known in KNOWN_DIRECTIONS:
return known
direction = active.get("direction")
return direction if isinstance(direction, str) and direction in KNOWN_DIRECTIONS else None
class EventEngine:
"""Advance one immutable round. State and returned events are JSON-compatible.
An evaluation block has anomaly(bool), direction(BUY/SELL/MIXED/UNKNOWN),
severity(0..3), metrics(dict), optionally reason_codes(list).
UNKNOWN preserves the last known direction for a later reversal check but
never asserts that direction for the current window. MIXED is observed
balance and resets that memory to MIXED. Missing direction defaults UNKNOWN.
Missing/invalid evaluations never resolve an active event.
Private state keys tell the publisher whether a CAS write is necessary;
they are not persisted. State must be loaded separately per trade_date.
"""
def advance(self, snapshot: dict, state: dict, published_at: datetime):
end = validate_snapshot(snapshot)
timing_policy = policy_version(snapshot)
now = aware_time(published_at)
original = {k: deepcopy(v) for k, v in (state or {}).items() if not k.startswith("_")}
if original.get("trade_date") not in (None, snapshot["trade_date"]):
raise ValueError("state must be isolated by trade_date")
version = int(original.get("state_version", 0))
def unchanged():
result = deepcopy(original)
result.update(_expected_version=version, _write_state=False)
return [], result
revision = snapshot.get("revision", 0)
last_end = aware_time(original["last_attempt_window_end"]) if original.get("last_attempt_window_end") else None
if snapshot.get("mode", "LIVE") == "REPLAY" or end > now:
return unchanged()
if last_end == end and original.get("last_round_id") != snapshot["round_id"]:
raise ValueError("one fixed window must have one stable round_id")
if last_end and (end < last_end or (end == last_end and revision <= original.get("last_revision", 0))):
return unchanged()
current = deepcopy(original)
current.setdefault("active", {})
current.setdefault("sequences", {})
events = []
def emit(active, event_state, evaluation=None, reason=None):
eid = active["event_id"]
seq = int(current["sequences"].get(eid, active.get("event_seq", 0))) + 1
current["sequences"][eid] = seq
active["event_seq"] = seq
event = {
"schema_version": 1,
"model_version": active["model_version"],
"baseline_version": snapshot.get("baseline_version"),
"producer_id": "mtf_etf",
"subject_type": active["subject_type"], "subject_id": active["subject_id"],
"scope": active["scope"], "trade_date": snapshot["trade_date"],
"round_id": snapshot["round_id"], "revision": revision,
"event_id": eid, "event_seq": seq, "event_state": event_state,
"timing_policy_version": policy_version(active),
"direction": active["direction"], "severity": active["severity"],
"direction_status": "UNAVAILABLE" if active["direction"] == "UNKNOWN" else "OK",
"last_known_direction": _last_known_direction(active),
"opened_at": active["opened_at"],
"window_start": (end - timedelta(minutes=15)).isoformat(),
"window_end": end.isoformat(), "published_at": now.isoformat(),
"valid_until": active["valid_until"],
"metrics": deepcopy((evaluation or {}).get("metrics", active.get("metrics", {}))),
"reason_codes": list((evaluation or {}).get("reason_codes", [])),
"flow_basis": "price_volume_proxy",
}
if snapshot.get("publication_mode") == "observation":
for field in ("publication_mode", "observation_contract_version", "purpose", "model_status",
"calibration_status", "threshold_version", "release_id", "trade_instruction"):
event[field] = snapshot[field]
if reason:
event["reason_codes"].append(reason)
if (event_state in {"OPEN", "CONTINUE"} and active["direction"] == "UNKNOWN"
and "DIRECTION_UNAVAILABLE" not in event["reason_codes"]):
event["reason_codes"].append("DIRECTION_UNAVAILABLE")
events.append(event)
return event
# A higher revision retracts only this round's previous emissions,
# then recalculates from its saved pre-round state. Sequence numbers
# remain monotonic even when an OPEN/CONTINUE is withdrawn.
is_revision = last_end == end
if is_revision:
for old in original.get("last_round_events", []):
emit(deepcopy(old), "RETRACTED", reason="SOURCE_REVISION")
current["active"] = deepcopy(original.get("last_round_base_active", {}))
base_active = deepcopy(current["active"])
# A late LIVE attempt still advances the watermark. It can expire a
# lease, but cannot manufacture a fresh live signal from stale data.
fresh = end <= now < admission_until(end, timing_policy) and snapshot.get("data_status") == "OK"
closing = bool(snapshot.get("session_closed")) or (end.hour == 15 and end.minute == 0)
for key, active in list(current["active"].items()):
if closing:
emit(active, "CLOSED", reason="SESSION_CLOSED")
del current["active"][key]
elif aware_time(active["valid_until"]) <= now:
emit(active, "EXPIRED", reason="LEASE_EXPIRED")
del current["active"][key]
if fresh and not closing:
seen = set()
for subject in snapshot["subjects"]:
for name in ("subject_type", "subject_id"):
if not subject.get(name):
raise ValueError("subject missing " + name)
identity = (subject["subject_type"], subject["subject_id"])
if identity in seen:
raise ValueError("duplicate subject")
seen.add(identity)
if subject.get("data_status") != "OK":
continue
for scope in SCOPES:
evaluation = subject.get(scope)
if not isinstance(evaluation, dict) or evaluation.get("data_status", "OK") != "OK":
continue
if not isinstance(evaluation.get("anomaly"), bool):
continue
direction = evaluation.get("direction", "UNKNOWN")
severity = evaluation.get("severity", 0)
if not isinstance(direction, str) or direction not in DIRECTIONS:
raise ValueError("unsupported pressure direction")
direction_status = "UNAVAILABLE" if direction == "UNKNOWN" else "OK"
if evaluation.get("direction_status", direction_status) != direction_status:
raise ValueError("direction_status contradicts pressure direction")
if type(severity) is not int or not 0 <= severity <= 3:
raise ValueError("severity must be an integer from 0 through 3")
key = _subject_key(subject, scope)
active = current["active"].get(key)
if active and active["model_version"] != snapshot["model_version"]:
emit(active, "CLOSED", reason="MODEL_CHANGED")
del current["active"][key]
active = None
if active and policy_version(active) != timing_policy:
emit(active, "CLOSED", reason="TIMING_POLICY_CHANGED")
del current["active"][key]
active = None
if not evaluation["anomaly"]:
if active:
emit(active, "RESOLVED", evaluation, "VALID_NORMAL_WINDOW")
del current["active"][key]
continue
last_known = _last_known_direction(active) if active else None
if active and {last_known, direction} == {"BUY", "SELL"}:
emit(active, "REVERSED", evaluation, "PRESSURE_DIRECTION_CHANGED")
del current["active"][key]
active = None
if active is None:
active = {
"event_id": _event_id(snapshot, subject, scope, direction),
"event_seq": 0, "model_version": snapshot["model_version"],
"timing_policy_version": timing_policy,
"subject_type": subject["subject_type"], "subject_id": subject["subject_id"],
"scope": scope, "direction": direction, "severity": severity,
"direction_status": direction_status,
"last_known_direction": direction if direction in KNOWN_DIRECTIONS else None,
"opened_at": end.isoformat(), "valid_until": lease_until(end, timing_policy).isoformat(),
"metrics": deepcopy(evaluation.get("metrics", {})),
}
current["active"][key] = active
emit(active, "OPEN", evaluation)
else:
active.update(direction=direction, severity=severity, valid_until=lease_until(end, timing_policy).isoformat(),
direction_status=direction_status,
last_known_direction=direction if direction in KNOWN_DIRECTIONS else last_known,
metrics=deepcopy(evaluation.get("metrics", {})))
emit(active, "CONTINUE", evaluation)
current.update(
schema_version=1, trade_date=snapshot["trade_date"], state_version=version + 1,
timing_policy_version=timing_policy,
last_attempt_window_end=end.isoformat(), last_seen_at=now.isoformat(),
last_round_id=snapshot["round_id"], last_revision=revision,
last_round_base_active=base_active,
last_round_events=deepcopy([e for e in events if e["event_state"] != "RETRACTED"]),
session_closed=closing, _expected_version=version, _write_state=True,
)
return events, current