267 lines
14 KiB
Python
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
|