Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(backtest): add Binance drift evidence artifacts

zygora111d951faa5e
diff --git a/agent/backtest/binance_shadow_evidence.py b/agent/backtest/binance_shadow_evidence.py
new file mode 100644
index 000000000..d97d96ec5
--- /dev/null
+++ b/agent/backtest/binance_shadow_evidence.py
@@ -0,0 +1,400 @@
+"""Deterministic Binance USD-M drift artifacts with no account action path."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+import json
+import math
+from pathlib import Path
+import re
+import tempfile
+from typing import Any, Mapping
+
+import pandas as pd
+
+from backtest.binance_account_reconciliation import (
+ BinanceAccountSnapshot,
+ ReconciliationTolerance,
+ reconcile_binance_account,
+)
+from backtest.perpetual_risk import AccountState, RiskSnapshot
+
+
+EVIDENCE_SCHEMA_VERSION = "binance-usdm-drift-evidence-v1"
+SUMMARY_SCHEMA_VERSION = "binance-usdm-drift-summary-v1"
+SUPPORTED_SNAPSHOT_SCHEMA = "binance-usdm-account-observation-v1"
+SUPPORTED_SOURCE_PROFILE = "binance-live-sdk-readonly"
+REQUIRED_SNAPSHOT_FIDELITY_FLAGS = frozenset({"client_observation_time", "sequential_signed_reads"})
+_SHA256 = re.compile(r"[0-9a-f]{64}")
+_EVIDENCE_FIELDS = frozenset(
+ {
+ "schema_version",
+ "status",
+ "severity",
+ "has_drift",
+ "expected_at",
+ "observed_at",
+ "source",
+ "source_profile",
+ "snapshot_schema_version",
+ "snapshot_configuration_hash",
+ "tolerance",
+ "comparisons",
+ "missing_on_exchange",
+ "unexpected_on_exchange",
+ "structural_differences",
+ "fidelity_flags",
+ "comparison_scope",
+ "liquidation_engine_assessment",
+ "rejection",
+ }
+)
+_COMPARISON_FIELDS = frozenset(
+ {
+ "field",
+ "local_value",
+ "exchange_value",
+ "absolute_delta",
+ "allowed_delta",
+ "within_tolerance",
+ "symbol",
+ }
+)
+
+
+def build_binance_drift_evidence(
+ local_account: AccountState,
+ local_risk: RiskSnapshot,
+ exchange_snapshot: BinanceAccountSnapshot,
+ *,
+ expected_timestamp: pd.Timestamp,
+ tolerance: ReconciliationTolerance = ReconciliationTolerance(),
+) -> dict[str, Any]:
+ """Build one comparison or fail-closed rejection record.
+
+ The returned record is evidence only. It never updates local accounting or
+ implies that Binance liquidation behavior has been validated.
+ """
+ expected = _utc_timestamp(expected_timestamp, "expected_timestamp")
+ observed = _utc_timestamp(exchange_snapshot.observed_at, "observed_at")
+ flags = list(
+ dict.fromkeys(
+ (
+ *local_risk.fidelity_flags,
+ *exchange_snapshot.fidelity_flags,
+ "account_snapshot_comparison_only",
+ )
+ )
+ )
+ record: dict[str, Any] = {
+ "schema_version": EVIDENCE_SCHEMA_VERSION,
+ "status": "comparison_rejected",
+ "severity": "rejected",
+ "has_drift": None,
+ "expected_at": expected.isoformat(),
+ "observed_at": observed.isoformat(),
+ "source": exchange_snapshot.source,
+ "source_profile": exchange_snapshot.source_profile,
+ "snapshot_schema_version": exchange_snapshot.schema_version,
+ "snapshot_configuration_hash": exchange_snapshot.configuration_hash,
+ "tolerance": {
+ "absolute": tolerance.absolute,
+ "relative": tolerance.relative,
+ "max_timestamp_skew_seconds": tolerance.max_timestamp_skew_seconds,
+ "version": tolerance.version,
+ },
+ "comparisons": [],
+ "missing_on_exchange": [],
+ "unexpected_on_exchange": [],
+ "structural_differences": [],
+ "fidelity_flags": flags,
+ "comparison_scope": "account_snapshot_fields_only",
+ "liquidation_engine_assessment": "not_assessed",
+ "rejection": None,
+ }
+
+ if exchange_snapshot.data_status != "complete":
+ record["rejection"] = {
+ "code": f"snapshot_{exchange_snapshot.data_status}",
+ "message": "exchange snapshot data_status must be complete",
+ "details": {"data_status": exchange_snapshot.data_status},
+ }
+ return record
+
+ invalid_provenance = _unsupported_snapshot_provenance(exchange_snapshot)
+ if invalid_provenance:
+ record["rejection"] = {
+ "code": "snapshot_unsupported_provenance",
+ "message": "exchange snapshot provenance is unsupported",
+ "details": {"invalid_fields": invalid_provenance},
+ }
+ return record
+
+ skew_seconds = abs((observed - expected).total_seconds())
+ if skew_seconds > tolerance.max_timestamp_skew_seconds:
+ record["rejection"] = {
+ "code": "timestamp_skew",
+ "message": "exchange snapshot timestamp skew exceeds tolerance",
+ "details": {
+ "timestamp_skew_seconds": skew_seconds,
+ "max_timestamp_skew_seconds": tolerance.max_timestamp_skew_seconds,
+ },
+ }
+ return record
+
+ report = reconcile_binance_account(
+ local_account,
+ local_risk,
+ exchange_snapshot,
+ expected_timestamp=expected,
+ tolerance=tolerance,
+ )
+ record.update(
+ {
+ "status": report.status,
+ "severity": "drift" if report.has_drift else "none",
+ "has_drift": report.has_drift,
+ "comparisons": [asdict(item) for item in report.comparisons],
+ "missing_on_exchange": list(report.missing_on_exchange),
+ "unexpected_on_exchange": list(report.unexpected_on_exchange),
+ "structural_differences": list(report.structural_differences),
+ "fidelity_flags": list(report.fidelity_flags),
+ "comparison_scope": report.comparison_scope,
+ "liquidation_engine_assessment": report.liquidation_engine_assessment,
+ }
+ )
+ return record
+
+
+def build_binance_drift_summary(evidence: Mapping[str, Any]) -> dict[str, Any]:
+ """Build the concise latest-observation summary for one evidence record."""
+ _validate_evidence(evidence)
+ comparisons = list(evidence["comparisons"])
+ rejection = evidence["rejection"]
+ return {
+ "schema_version": SUMMARY_SCHEMA_VERSION,
+ "latest_status": evidence["status"],
+ "severity": evidence["severity"],
+ "has_drift": evidence["has_drift"],
+ "observed_at": evidence["observed_at"],
+ "source": evidence["source"],
+ "source_profile": evidence["source_profile"],
+ "snapshot_schema_version": evidence["snapshot_schema_version"],
+ "snapshot_configuration_hash": evidence["snapshot_configuration_hash"],
+ "tolerance": dict(evidence["tolerance"]),
+ "tolerance_version": evidence["tolerance"]["version"],
+ "comparison_count": len(comparisons),
+ "out_of_tolerance_count": sum(not item["within_tolerance"] for item in comparisons),
+ "missing_symbol_count": len(evidence["missing_on_exchange"]),
+ "unexpected_symbol_count": len(evidence["unexpected_on_exchange"]),
+ "structural_difference_count": len(evidence["structural_differences"]),
+ "rejection_code": (rejection.get("code") if isinstance(rejection, Mapping) else None),
+ "fidelity_flags": list(evidence["fidelity_flags"]),
+ "comparison_scope": evidence["comparison_scope"],
+ "liquidation_engine_assessment": evidence["liquidation_engine_assessment"],
+ }
+
+
+def write_binance_drift_evidence(
+ run_dir: Path | str,
+ evidence: Mapping[str, Any],
+) -> tuple[Path, Path]:
+ """Append one strict JSONL record and replace its latest summary."""
+ summary = build_binance_drift_summary(evidence)
+ evidence_json = json.dumps(
+ evidence,
+ sort_keys=True,
+ allow_nan=False,
+ separators=(",", ":"),
+ )
+ summary_json = json.dumps(
+ summary,
+ indent=2,
+ sort_keys=True,
+ allow_nan=False,
+ )
+
+ artifact_dir = Path(run_dir) / "artifacts"
+ artifact_dir.mkdir(parents=True, exist_ok=True)
+ jsonl_path = artifact_dir / "binance_drift.jsonl"
+ summary_path = artifact_dir / "binance_drift_summary.json"
+ with jsonl_path.open("a", encoding="utf-8", newline="\n") as handle:
+ handle.write(evidence_json + "\n")
+ temp_path: Path | None = None
+ try:
+ with tempfile.NamedTemporaryFile(
+ "w",
+ encoding="utf-8",
+ newline="\n",
+ dir=artifact_dir,
+ prefix=f".{summary_path.name}.",
+ suffix=".tmp",
+ delete=False,
+ ) as handle:
+ handle.write(summary_json + "\n")
+ temp_path = Path(handle.name)
+ temp_path.replace(summary_path)
+ finally:
+ if temp_path is not None and temp_path.exists():
+ temp_path.unlink()
+ return jsonl_path, summary_path
+
+
+def _utc_timestamp(value: pd.Timestamp, name: str) -> pd.Timestamp:
+ if not isinstance(value, pd.Timestamp) or pd.isna(value) or value.tzinfo is None:
+ raise ValueError(f"{name} must be a timezone-aware pandas Timestamp")
+ return value.tz_convert("UTC")
+
+
+def _unsupported_snapshot_provenance(snapshot: BinanceAccountSnapshot) -> list[str]:
+ invalid: list[str] = []
+ if snapshot.schema_version != SUPPORTED_SNAPSHOT_SCHEMA:
+ invalid.append("schema_version")
+ if snapshot.source_profile != SUPPORTED_SOURCE_PROFILE:
+ invalid.append("source_profile")
+ if _SHA256.fullmatch(snapshot.configuration_hash) is None:
+ invalid.append("configuration_hash")
+ if not REQUIRED_SNAPSHOT_FIDELITY_FLAGS.issubset(snapshot.fidelity_flags):
+ invalid.append("fidelity_flags")
+ return invalid
+
+
+def _validate_evidence(evidence: Mapping[str, Any]) -> None:
+ if set(evidence) != _EVIDENCE_FIELDS:
+ raise ValueError("Binance drift evidence fields do not match its schema")
+ if evidence.get("schema_version") != EVIDENCE_SCHEMA_VERSION:
+ raise ValueError("unsupported Binance drift evidence schema")
+ if evidence.get("comparison_scope") != "account_snapshot_fields_only":
+ raise ValueError("Binance drift evidence comparison scope is unsupported")
+ if evidence.get("liquidation_engine_assessment") != "not_assessed":
+ raise ValueError("Binance drift evidence cannot assess the liquidation engine")
+
+ _validate_timestamp_text(evidence["expected_at"], "expected_at")
+ _validate_timestamp_text(evidence["observed_at"], "observed_at")
+ if evidence["source"] != "binance-usdm":
+ raise ValueError("Binance drift evidence source is unsupported")
+ for field in (
+ "source_profile",
+ "snapshot_schema_version",
+ "snapshot_configuration_hash",
+ ):
+ if not isinstance(evidence[field], str) or not evidence[field]:
+ raise ValueError(f"Binance drift evidence {field} must be a non-empty string")
+
+ tolerance = evidence["tolerance"]
+ if not isinstance(tolerance, Mapping) or set(tolerance) != {
+ "absolute",
+ "relative",
+ "max_timestamp_skew_seconds",
+ "version",
+ }:
+ raise ValueError("Binance drift evidence tolerance is malformed")
+ for field in ("absolute", "relative", "max_timestamp_skew_seconds"):
+ _validate_number(tolerance[field], f"tolerance.{field}", non_negative=True)
+ if not isinstance(tolerance["version"], str) or not tolerance["version"]:
+ raise ValueError("Binance drift evidence tolerance version is malformed")
+
+ comparisons = evidence["comparisons"]
+ if not isinstance(comparisons, list):
+ raise ValueError("Binance drift evidence comparisons must be a list")
+ for item in comparisons:
+ _validate_comparison(item)
+ for field in ("missing_on_exchange", "unexpected_on_exchange", "structural_differences"):
+ _validate_string_list(evidence[field], field)
+ _validate_string_list(evidence["fidelity_flags"], "fidelity_flags")
+ required_flags = {"account_snapshot_comparison_only"}
+ if evidence["status"] == "comparison_complete":
+ required_flags.update(REQUIRED_SNAPSHOT_FIDELITY_FLAGS)
+ if not required_flags.issubset(evidence["fidelity_flags"]):
+ raise ValueError("Binance drift evidence is missing required fidelity flags")
+
+ status = evidence.get("status")
+ severity = evidence.get("severity")
+ has_drift = evidence.get("has_drift")
+ rejection = evidence.get("rejection")
+ if status == "comparison_complete":
+ if (
+ evidence["snapshot_schema_version"] != SUPPORTED_SNAPSHOT_SCHEMA
+ or evidence["source_profile"] != SUPPORTED_SOURCE_PROFILE
+ or _SHA256.fullmatch(evidence["snapshot_configuration_hash"]) is None
+ ):
+ raise ValueError("completed Binance drift evidence has unsupported provenance")
+ derived_drift = bool(
+ evidence["missing_on_exchange"]
+ or evidence["unexpected_on_exchange"]
+ or evidence["structural_differences"]
+ or any(not item["within_tolerance"] for item in comparisons)
+ )
+ expected_severity = "drift" if derived_drift else "none"
+ if has_drift is not derived_drift or severity != expected_severity or rejection is not None:
+ raise ValueError("completed Binance drift evidence is internally inconsistent")
+ elif status == "comparison_rejected":
+ if (
+ has_drift is not None
+ or severity != "rejected"
+ or not isinstance(rejection, Mapping)
+ or set(rejection) != {"code", "message", "details"}
+ or not isinstance(rejection["code"], str)
+ or not rejection["code"]
+ or not isinstance(rejection["message"], str)
+ or not rejection["message"]
+ or not isinstance(rejection["details"], Mapping)
+ or comparisons
+ or evidence["missing_on_exchange"]
+ or evidence["unexpected_on_exchange"]
+ or evidence["structural_differences"]
+ ):
+ raise ValueError("rejected Binance drift evidence is internally inconsistent")
+ else:
+ raise ValueError("unsupported Binance drift evidence status")
+
+
+def _validate_timestamp_text(value: Any, name: str) -> None:
+ if not isinstance(value, str):
+ raise ValueError(f"Binance drift evidence {name} must be an ISO timestamp")
+ try:
+ _utc_timestamp(pd.Timestamp(value), name)
+ except (TypeError, ValueError) as exc:
+ raise ValueError(f"Binance drift evidence {name} must be an ISO timestamp") from exc
+
+
+def _validate_number(value: Any, name: str, *, non_negative: bool = False) -> None:
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+ raise ValueError(f"Binance drift evidence {name} must be finite")
+ if non_negative and value < 0:
+ raise ValueError(f"Binance drift evidence {name} must be non-negative")
+
+
+def _validate_string_list(value: Any, name: str) -> None:
+ if (
+ not isinstance(value, list)
+ or any(not isinstance(item, str) or not item for item in value)
+ or len(value) != len(set(value))
+ ):
+ raise ValueError(f"Binance drift evidence {name} must contain unique strings")
+
+
+def _validate_comparison(item: Any) -> None:
+ if not isinstance(item, Mapping) or set(item) != _COMPARISON_FIELDS:
+ raise ValueError("Binance drift evidence comparison is malformed")
+ if not isinstance(item["field"], str) or not item["field"]:
+ raise ValueError("Binance drift evidence comparison field is malformed")
+ for field in ("local_value", "exchange_value", "absolute_delta", "allowed_delta"):
+ _validate_number(
+ item[field],
+ f"comparison.{field}",
+ non_negative=field in {"absolute_delta", "allowed_delta"},
+ )
+ if not isinstance(item["within_tolerance"], bool):
+ raise ValueError("Binance drift evidence comparison tolerance result is malformed")
+ if item["symbol"] is not None and (not isinstance(item["symbol"], str) or not item["symbol"]):
+ raise ValueError("Binance drift evidence comparison symbol is malformed")
+ if not math.isclose(
+ item["absolute_delta"],
+ abs(item["local_value"] - item["exchange_value"]),
+ rel_tol=1e-12,
+ abs_tol=1e-12,
+ ):
+ raise ValueError("Binance drift evidence comparison delta is inconsistent")
+ if item["within_tolerance"] is not (item["absolute_delta"] <= item["allowed_delta"]):
+ raise ValueError("Binance drift evidence comparison tolerance result is inconsistent")
diff --git a/agent/tests/test_binance_shadow_evidence.py b/agent/tests/test_binance_shadow_evidence.py
new file mode 100644
index 000000000..4b3bb776c
--- /dev/null
+++ b/agent/tests/test_binance_shadow_evidence.py
@@ -0,0 +1,506 @@
+"""Deterministic artifact integration for Binance USD-M shadow reconciliation."""
+
+from __future__ import annotations
+
+import ast
+from copy import deepcopy
+import inspect
+import json
+
+import pandas as pd
+import pytest
+
+import backtest.binance_shadow_evidence as evidence_module
+from backtest.binance_account_reconciliation import (
+ BinanceAccountSnapshot,
+ BinancePositionSnapshot,
+ ReconciliationTolerance,
+)
+from backtest.binance_shadow_evidence import (
+ build_binance_drift_evidence,
+ build_binance_drift_summary,
+ write_binance_drift_evidence,
+)
+from backtest.perpetual_risk import (
+ AccountState,
+ PositionRisk,
+ PositionState,
+ RiskSnapshot,
+)
+
+
+OBSERVED_AT = pd.Timestamp("2026-08-27T08:00:00Z")
+
+
+def _local_cross() -> tuple[AccountState, RiskSnapshot]:
+ position = PositionState("BTC-USDT-PERP", 0.1, 60_000.0, 10.0, 3.0, None)
+ account = AccountState(1_000.0, (position,), "cross")
+ risk = PositionRisk("BTC-USDT-PERP", 61_000.0, 6_100.0, 100.0, 610.0, 24.4, None)
+ return account, RiskSnapshot(
+ 1_100.0,
+ 610.0,
+ 24.4,
+ 490.0,
+ (risk,),
+ "healthy",
+ (),
+ ("conservative_intrabar_assumption",),
+ )
+
+
+def _local_isolated() -> tuple[AccountState, RiskSnapshot, BinanceAccountSnapshot]:
+ position = PositionState("BTC-USDT-PERP", 0.1, 60_000.0, 10.0, 3.0, 700.0)
+ account = AccountState(1_000.0, (position,), "isolated")
+ risk = PositionRisk("BTC-USDT-PERP", 61_000.0, 6_100.0, 100.0, 610.0, 24.4, 800.0)
+ snapshot = RiskSnapshot(
+ 1_100.0,
+ 610.0,
+ 24.4,
+ 490.0,
+ (risk,),
+ "healthy",
+ (),
+ ("conservative_intrabar_assumption",),
+ )
+ exchange = _exchange_cross(
+ positions=(
+ BinancePositionSnapshot(
+ "BTC-USDT-PERP",
+ 0.1,
+ 60_000.0,
+ 10.0,
+ "isolated",
+ 700.0,
+ 100.0,
+ 610.0,
+ 24.4,
+ ),
+ )
+ )
+ return account, snapshot, exchange
+
+
+def _exchange_cross(**changes: object) -> BinanceAccountSnapshot:
+ values: dict[str, object] = {
+ "schema_version": "binance-usdm-account-observation-v1",
+ "observed_at": OBSERVED_AT,
+ "source": "binance-usdm",
+ "source_profile": "binance-live-sdk-readonly",
+ "configuration_hash": "a" * 64,
+ "data_status": "complete",
+ "wallet_balance": 1_000.0,
+ "margin_balance": 1_100.0,
+ "available_balance": 490.0,
+ "total_unrealized_pnl": 100.0,
+ "total_initial_margin": 610.0,
+ "total_maintenance_margin": 24.4,
+ "positions": (
+ BinancePositionSnapshot(
+ "BTC-USDT-PERP",
+ 0.1,
+ 60_000.0,
+ 10.0,
+ "cross",
+ None,
+ 100.0,
+ 610.0,
+ 24.4,
+ ),
+ ),
+ "fidelity_flags": (
+ "client_observation_time",
+ "sequential_signed_reads",
+ ),
+ }
+ values.update(changes)
+ return BinanceAccountSnapshot(**values) # type: ignore[arg-type]
+
+
+def _tolerance() -> ReconciliationTolerance:
+ return ReconciliationTolerance(
+ absolute=0.01,
+ relative=0.001,
+ max_timestamp_skew_seconds=2.0,
+ version="shadow-live-tolerance-v1",
+ )
+
+
+def test_complete_evidence_is_deterministic_and_never_claims_engine_validation() -> None:
+ account, risk = _local_cross()
+
+ first = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+ second = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ assert first == second
+ assert first["schema_version"] == "binance-usdm-drift-evidence-v1"
+ assert first["status"] == "comparison_complete"
+ assert first["severity"] == "none"
+ assert first["has_drift"] is False
+ assert first["expected_at"] == "2026-08-27T08:00:00+00:00"
+ assert first["observed_at"] == "2026-08-27T08:00:00+00:00"
+ assert first["tolerance"] == {
+ "absolute": 0.01,
+ "relative": 0.001,
+ "max_timestamp_skew_seconds": 2.0,
+ "version": "shadow-live-tolerance-v1",
+ }
+ assert first["comparison_scope"] == "account_snapshot_fields_only"
+ assert first["liquidation_engine_assessment"] == "not_assessed"
+ assert first["rejection"] is None
+ assert len(first["comparisons"]) == 12
+ assert all(item["within_tolerance"] for item in first["comparisons"])
+ assert first["fidelity_flags"] == [
+ "conservative_intrabar_assumption",
+ "client_observation_time",
+ "sequential_signed_reads",
+ "account_snapshot_comparison_only",
+ ]
+
+
+def test_drift_evidence_preserves_numeric_structural_and_symbol_findings() -> None:
+ account, risk = _local_cross()
+ eth = BinancePositionSnapshot("ETH-USDT-PERP", -1.0, 3_000.0, 5.0, "isolated", 600.0, 0.0, 600.0, 12.0)
+ exchange = _exchange_cross(
+ wallet_balance=900.0,
+ positions=(
+ BinancePositionSnapshot(
+ "BTC-USDT-PERP",
+ 0.2,
+ 60_000.0,
+ 10.0,
+ "isolated",
+ 610.0,
+ 100.0,
+ 610.0,
+ 24.4,
+ ),
+ eth,
+ ),
+ )
+
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ exchange,
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ assert record["has_drift"] is True
+ assert record["severity"] == "drift"
+ assert record["unexpected_on_exchange"] == ["ETH-USDT-PERP"]
+ assert record["structural_differences"] == [
+ "BTC-USDT-PERP:margin_mode:local=cross:exchange=isolated",
+ "BTC-USDT-PERP:isolated_margin_presence",
+ ]
+ drifted = {(item["symbol"], item["field"]) for item in record["comparisons"] if not item["within_tolerance"]}
+ assert (None, "wallet_balance") in drifted
+ assert ("BTC-USDT-PERP", "quantity") in drifted
+
+
+def test_complete_isolated_evidence_includes_position_collateral() -> None:
+ account, risk, exchange = _local_isolated()
+
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ exchange,
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ assert record["status"] == "comparison_complete"
+ assert record["has_drift"] is False
+ isolated = next(item for item in record["comparisons"] if item["field"] == "isolated_margin")
+ assert isolated["within_tolerance"] is True
+
+
+ ("changes", "detail"),
+ [
+ ({"schema_version": "tampered-schema"}, "schema_version"),
+ ({"source_profile": "tampered-profile"}, "source_profile"),
+ ({"configuration_hash": "not-a-sha256"}, "configuration_hash"),
+ ({"fidelity_flags": ("client_observation_time",)}, "fidelity_flags"),
+ ],
+)
+def test_complete_snapshot_with_unsupported_provenance_is_rejected(
+ changes: dict[str, object],
+ detail: str,
+) -> None:
+ account, risk = _local_cross()
+
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(**changes),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ assert record["status"] == "comparison_rejected"
+ assert record["has_drift"] is None
+ assert record["rejection"]["code"] == "snapshot_unsupported_provenance"
+ assert detail in record["rejection"]["details"]["invalid_fields"]
+
+
+def test_unsupported_provenance_rejection_can_be_persisted(tmp_path) -> None:
+ account, risk = _local_cross()
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(fidelity_flags=("client_observation_time",)),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ jsonl_path, summary_path = write_binance_drift_evidence(tmp_path, record)
+
+ assert json.loads(jsonl_path.read_text(encoding="utf-8"))["status"] == "comparison_rejected"
+ summary = json.loads(summary_path.read_text(encoding="utf-8"))
+ assert summary["rejection_code"] == "snapshot_unsupported_provenance"
+ assert summary["has_drift"] is None
+
+
+ ("snapshot", "expected_at", "code"),
+ [
+ (_exchange_cross(data_status="incomplete"), OBSERVED_AT, "snapshot_incomplete"),
+ (_exchange_cross(data_status="unsupported"), OBSERVED_AT, "snapshot_unsupported"),
+ (
+ _exchange_cross(),
+ pd.Timestamp("2026-08-27T08:00:05Z"),
+ "timestamp_skew",
+ ),
+ ],
+)
+def test_rejected_observation_still_produces_fail_closed_evidence(
+ snapshot: BinanceAccountSnapshot,
+ expected_at: pd.Timestamp,
+ code: str,
+) -> None:
+ account, risk = _local_cross()
+
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ snapshot,
+ expected_timestamp=expected_at,
+ tolerance=_tolerance(),
+ )
+
+ assert record["status"] == "comparison_rejected"
+ assert record["severity"] == "rejected"
+ assert record["has_drift"] is None
+ assert record["comparisons"] == []
+ assert record["rejection"]["code"] == code
+ assert record["liquidation_engine_assessment"] == "not_assessed"
+ assert build_binance_drift_summary(record)["rejection_code"] == code
+
+
+def test_summary_is_concise_and_machine_readable() -> None:
+ account, risk = _local_cross()
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(wallet_balance=900.0),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ assert build_binance_drift_summary(record) == {
+ "schema_version": "binance-usdm-drift-summary-v1",
+ "latest_status": "comparison_complete",
+ "severity": "drift",
+ "has_drift": True,
+ "observed_at": "2026-08-27T08:00:00+00:00",
+ "source": "binance-usdm",
+ "source_profile": "binance-live-sdk-readonly",
+ "snapshot_schema_version": "binance-usdm-account-observation-v1",
+ "snapshot_configuration_hash": "a" * 64,
+ "tolerance": {
+ "absolute": 0.01,
+ "relative": 0.001,
+ "max_timestamp_skew_seconds": 2.0,
+ "version": "shadow-live-tolerance-v1",
+ },
+ "tolerance_version": "shadow-live-tolerance-v1",
+ "comparison_count": 12,
+ "out_of_tolerance_count": 1,
+ "missing_symbol_count": 0,
+ "unexpected_symbol_count": 0,
+ "structural_difference_count": 0,
+ "rejection_code": None,
+ "fidelity_flags": [
+ "conservative_intrabar_assumption",
+ "client_observation_time",
+ "sequential_signed_reads",
+ "account_snapshot_comparison_only",
+ ],
+ "comparison_scope": "account_snapshot_fields_only",
+ "liquidation_engine_assessment": "not_assessed",
+ }
+
+
+def test_writer_appends_jsonl_and_replaces_latest_summary(tmp_path) -> None:
+ account, risk = _local_cross()
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ latest = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(wallet_balance=900.0),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ paths = write_binance_drift_evidence(tmp_path, record)
+ write_binance_drift_evidence(tmp_path, latest)
+
+ jsonl_path = tmp_path / "artifacts" / "binance_drift.jsonl"
+ summary_path = tmp_path / "artifacts" / "binance_drift_summary.json"
+ assert paths == (jsonl_path, summary_path)
+ assert [json.loads(line) for line in jsonl_path.read_text(encoding="utf-8").splitlines()] == [
+ record,
+ latest,
+ ]
+ assert json.loads(summary_path.read_text(encoding="utf-8")) == build_binance_drift_summary(latest)
+ assert summary_path.read_text(encoding="utf-8").endswith("\n")
+ assert list(summary_path.parent.glob("*.tmp")) == []
+
+
+def test_writer_rejects_non_finite_evidence_without_partial_artifact(tmp_path) -> None:
+ account, risk = _local_cross()
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+ malformed = deepcopy(record)
+ malformed["comparisons"][0]["local_value"] = float("nan")
+
+ with pytest.raises(ValueError):
+ write_binance_drift_evidence(tmp_path, malformed)
+
+ assert not (tmp_path / "artifacts" / "binance_drift.jsonl").exists()
+
+
+ ("field", "value"),
+ [
+ ("schema_version", "unknown-schema"),
+ ("liquidation_engine_assessment", "validated"),
+ ("comparison_scope", "liquidation_engine"),
+ ],
+)
+def test_writer_rejects_tampered_scope_or_validation_claim(
+ tmp_path,
+ field: str,
+ value: str,
+) -> None:
+ account, risk = _local_cross()
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+ record[field] = value
+
+ with pytest.raises(ValueError):
+ write_binance_drift_evidence(tmp_path, record)
+
+ assert not (tmp_path / "artifacts" / "binance_drift.jsonl").exists()
+
+
+def test_writer_rejects_missing_or_contradictory_evidence(tmp_path) -> None:
+ account, risk = _local_cross()
+ record = build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+ malformed_records = []
+
+ missing_tolerance = deepcopy(record)
+ missing_tolerance["tolerance"] = {}
+ malformed_records.append(missing_tolerance)
+
+ malformed_flags = deepcopy(record)
+ malformed_flags["fidelity_flags"] = "client_observation_time"
+ malformed_records.append(malformed_flags)
+
+ contradictory_comparison = deepcopy(record)
+ contradictory_comparison["comparisons"][0]["within_tolerance"] = False
+ malformed_records.append(contradictory_comparison)
+
+ contradictory_symbols = deepcopy(record)
+ contradictory_symbols["missing_on_exchange"] = ["ETH-USDT-PERP"]
+ malformed_records.append(contradictory_symbols)
+
+ tampered_source = deepcopy(record)
+ tampered_source["source_profile"] = "live-order-profile"
+ malformed_records.append(tampered_source)
+
+ for malformed in malformed_records:
+ with pytest.raises(ValueError):
+ write_binance_drift_evidence(tmp_path, malformed)
+
+ assert not (tmp_path / "artifacts" / "binance_drift.jsonl").exists()
+
+
+def test_evidence_path_is_read_only_and_cannot_import_live_connectors() -> None:
+ account, risk = _local_cross()
+ before = (account, risk)
+
+ build_binance_drift_evidence(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ tolerance=_tolerance(),
+ )
+
+ assert (account, risk) == before
+ tree = ast.parse(inspect.getsource(evidence_module))
+ forbidden_imports = (
+ "aiohttp",
+ "backtest.engines",
+ "ccxt",
+ "httpx",
+ "requests",
+ "socket",
+ "src.live",
+ "src.trading",
+ "subprocess",
+ "urllib",
+ "websocket",
+ )
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Import):
+ assert not any(alias.name.startswith(forbidden_imports) for alias in node.names)
+ if isinstance(node, ast.ImportFrom) and node.module:
+ assert not node.module.startswith(forbidden_imports)